From c686e17e52eb9964137fd1a46fbbc96e368b6286 Mon Sep 17 00:00:00 2001 From: Corbin Simpson Date: Sun, 20 Dec 2009 15:00:40 -0800 Subject: Add Gallium docs. In Sphinx/ReST format. --- src/gallium/docs/source/cso/dsa.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 src/gallium/docs/source/cso/dsa.rst (limited to 'src/gallium/docs/source/cso/dsa.rst') diff --git a/src/gallium/docs/source/cso/dsa.rst b/src/gallium/docs/source/cso/dsa.rst new file mode 100644 index 00000000000..5f23896f6e7 --- /dev/null +++ b/src/gallium/docs/source/cso/dsa.rst @@ -0,0 +1,23 @@ +Depth, Stencil, & Alpha +======================= + +These three states control the depth, stencil, and alpha tests, used to +discard fragments that have passed through the fragment shader. + +Traditionally, these three tests have been clumped together in hardware, so +they are all stored in one structure. + +Depth Members +------------- + +XXX + +Stencil Members +--------------- + +XXX + +Alpha Members +------------- + +XXX -- cgit v1.2.3 From c80f2b04e0d235cfe623c968a670e6d34b8c2add Mon Sep 17 00:00:00 2001 From: Corbin Simpson Date: Sun, 20 Dec 2009 16:40:39 -0800 Subject: Fill out some of the CSO info. ...And looks like there's already things I don't know. Go figure. --- src/gallium/docs/source/cso.rst | 7 ++++++ src/gallium/docs/source/cso/blend.rst | 2 +- src/gallium/docs/source/cso/dsa.rst | 39 ++++++++++++++++++++++++++++++--- src/gallium/docs/source/cso/sampler.rst | 36 +++++++++++++++++++++++++++++- 4 files changed, 79 insertions(+), 5 deletions(-) (limited to 'src/gallium/docs/source/cso/dsa.rst') diff --git a/src/gallium/docs/source/cso.rst b/src/gallium/docs/source/cso.rst index f00cc51d4bf..dab1ee50f39 100644 --- a/src/gallium/docs/source/cso.rst +++ b/src/gallium/docs/source/cso.rst @@ -1,6 +1,13 @@ CSO === +CSO, Constant State Objects, are a core part of Gallium's API. + +CSO work on the principle of reusable state; they are created by filling +out a state object with the desired properties, then passing that object +to a context. The context returns an opaque context-specific handle which +can be bound at any time for the desired effect. + .. toctree:: :glob: diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst index e32d324854f..608f36999bf 100644 --- a/src/gallium/docs/source/cso/blend.rst +++ b/src/gallium/docs/source/cso/blend.rst @@ -9,4 +9,4 @@ XXX it is unresolved what behavior should result if blend_enable is off. Members ------- -XXX +XXX undocumented members diff --git a/src/gallium/docs/source/cso/dsa.rst b/src/gallium/docs/source/cso/dsa.rst index 5f23896f6e7..0be7af5029a 100644 --- a/src/gallium/docs/source/cso/dsa.rst +++ b/src/gallium/docs/source/cso/dsa.rst @@ -7,17 +7,50 @@ discard fragments that have passed through the fragment shader. Traditionally, these three tests have been clumped together in hardware, so they are all stored in one structure. +During actual execution, the order of operations done on fragments is always: + +* Stencil +* Depth +* Alpha + Depth Members ------------- -XXX +enabled + Whether the depth test is enabled. +writemask + Whether the depth buffer receives depth writes. +func + The depth test function. One of PIPE_FUNC. Stencil Members --------------- -XXX +XXX document valuemask, writemask + +enabled + Whether the stencil test is enabled. For the second stencil, whether the + two-sided stencil is enabled. +func + The stencil test function. One of PIPE_FUNC. +ref_value + Stencil test reference value; used for certain functions. +fail_op + The operation to carry out if the stencil test fails. One of + PIPE_STENCIL_OP. +zfail_op + The operation to carry out if the stencil test passes but the depth test + fails. One of PIPE_STENCIL_OP. +zpass_op + The operation to carry out if the stencil test and depth test both pass. + One of PIPE_STENCIL_OP. Alpha Members ------------- -XXX +enabled + Whether the alpha test is enabled. +func + The alpha test function. One of PIPE_FUNC. +ref_value + Alpha test reference value; used for certain functions. diff --git a/src/gallium/docs/source/cso/sampler.rst b/src/gallium/docs/source/cso/sampler.rst index 09b959ffffe..3a63ac637bd 100644 --- a/src/gallium/docs/source/cso/sampler.rst +++ b/src/gallium/docs/source/cso/sampler.rst @@ -4,7 +4,41 @@ Sampler Texture units have many options for selecting texels from loaded textures; this state controls an individual texture unit's texel-sampling settings. +Texture coordinates are always treated as four-dimensional, and referred to +with the traditional (S, T, R, Q) notation. + Members ------- -XXX +XXX undocumented compare_mode, compare_func + +wrap_s + How to wrap the S coordinate. One of PIPE_TEX_WRAP. +wrap_t + How to wrap the T coordinate. One of PIPE_TEX_WRAP. +wrap_r + How to wrap the R coordinate. One of PIPE_TEX_WRAP. +min_img_filter + The filter to use when minifying texels. One of PIPE_TEX_FILTER. +min_mip_filter + The filter to use when minifying mipmapped textures. One of + PIPE_TEX_FILTER. +mag_img_filter + The filter to use when magnifying texels. One of PIPE_TEX_FILTER. +normalized_coords + Whether the texture coordinates are normalized. If normalized, they will + always be in [0, 1]. If not, they will be in the range of each dimension + of the loaded texture. +prefilter + XXX From the Doxy, "weird sampling state exposed by some APIs." Refine. +lod_bias + The bias to apply to the level of detail. +min_lod + Minimum level of detail, used to clamp LoD after bias. +max_lod + Maximum level of detail, used to clamp LoD after bias. +border_color + RGBA color used for out-of-bounds coordinates. +max_anisotropy + Maximum filtering to apply anisotropically to textures. Setting this to + 1.0 effectively disables anisotropic filtering. -- cgit v1.2.3 From a524aab8ae356b3ef35392fa7375a862ed3322dc Mon Sep 17 00:00:00 2001 From: Corbin Simpson Date: Sun, 20 Dec 2009 19:41:50 -0800 Subject: Moar docs, mostly context. --- src/gallium/docs/source/context.rst | 73 +++++++++++++++++++++++++++++- src/gallium/docs/source/cso/blend.rst | 2 + src/gallium/docs/source/cso/dsa.rst | 2 + src/gallium/docs/source/cso/rasterizer.rst | 2 + src/gallium/docs/source/cso/sampler.rst | 2 + src/gallium/docs/source/cso/shader.rst | 2 + src/gallium/docs/source/screen.rst | 32 ++++++++++++- 7 files changed, 113 insertions(+), 2 deletions(-) (limited to 'src/gallium/docs/source/cso/dsa.rst') diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index c2e23a13103..6470e8fd492 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -7,4 +7,75 @@ of the device's 3D rendering pipeline. Methods ------- -XXX +CSO State +^^^^^^^^^ + +All CSO state is created, bound, and destroyed, with triplets of methods that +all follow a specific naming scheme. For example, ``create_blend_state``, +``bind_blend_state``, and ``destroy_blend_state``. + +CSO objects handled by the context object: + +* :ref:`Blend`: ``*_blend_state`` +* :ref:`Sampler`: These are special; they can be bound to either vertex or + fragment samplers, and they are bound in groups. + ``bind_fragment_sampler_states``, ``bind_vertex_sampler_states`` +* :ref:`Rasterizer`: ``*_rasterizer_state`` +* :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state`` +* :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for + fragment shaders, and ``*_vs_state`` is for vertex shaders. + +Non-CSO State +^^^^^^^^^^^^^ + +These pieces of state are too small, variable, and/or trivial to have CSO +objects. They all follow simple, one-method binding calls, e.g. +``set_edgeflags``. + +* ``set_edgeflags`` +* ``set_blend_color`` +* ``set_clip_state`` +* ``set_constant_buffer`` +* ``set_framebuffer_state`` +* ``set_polygon_stipple`` +* ``set_scissor_state`` +* ``set_viewport_state`` +* ``set_fragment_sampler_textures`` +* ``set_vertex_sampler_textures`` +* ``set_vertex_buffers`` +* ``set_vertex_elements`` + +Queries +^^^^^^^ + +Queries can be created with ``create_query`` and deleted with +``destroy_query``. To enable a query, use ``begin_query``, and when finished, +use ``end_query`` to stop the query. Finally, ``get_query_result`` is used +to retrieve the results. + +VBO Drawing +^^^^^^^^^^^ + +``draw_arrays`` + +``draw_elements`` + +``draw_range_elements`` + +``flush`` + +Surface Drawing +^^^^^^^^^^^^^^^ + +These methods emulate classic blitter controls. They are not guaranteed to be +available; if they are set to NULL, then they are not present. + +``surface_fill`` performs a fill operation on a section of a surface. + +``surface_copy`` blits a region of a surface to a region of another surface, +provided that both surfaces are the same format. The source and destination +may be the same surface, and overlapping blits are permitted. + +``clear`` initializes entire buffers to an RGBA, depth, or stencil value, +depending on the formats of the buffers. Use ``set_framebuffer_state`` to +specify the buffers to clear. diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst index 608f36999bf..fd9e4a1e2d5 100644 --- a/src/gallium/docs/source/cso/blend.rst +++ b/src/gallium/docs/source/cso/blend.rst @@ -1,3 +1,5 @@ +.. _blend: + Blend ===== diff --git a/src/gallium/docs/source/cso/dsa.rst b/src/gallium/docs/source/cso/dsa.rst index 0be7af5029a..12abaa9d6fe 100644 --- a/src/gallium/docs/source/cso/dsa.rst +++ b/src/gallium/docs/source/cso/dsa.rst @@ -1,3 +1,5 @@ +.. _depth,stencil,&alpha: + Depth, Stencil, & Alpha ======================= diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst index b87d121db3f..0686bffa1e0 100644 --- a/src/gallium/docs/source/cso/rasterizer.rst +++ b/src/gallium/docs/source/cso/rasterizer.rst @@ -1,3 +1,5 @@ +.. _rasterizer: + Rasterizer ========== diff --git a/src/gallium/docs/source/cso/sampler.rst b/src/gallium/docs/source/cso/sampler.rst index 3a63ac637bd..e3f1757f57a 100644 --- a/src/gallium/docs/source/cso/sampler.rst +++ b/src/gallium/docs/source/cso/sampler.rst @@ -1,3 +1,5 @@ +.. _sampler: + Sampler ======= diff --git a/src/gallium/docs/source/cso/shader.rst b/src/gallium/docs/source/cso/shader.rst index 9e1cb35be06..0ee42c87876 100644 --- a/src/gallium/docs/source/cso/shader.rst +++ b/src/gallium/docs/source/cso/shader.rst @@ -1,3 +1,5 @@ +.. _shader: + Shader ====== diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst index 1877718e3d5..9631e6967ef 100644 --- a/src/gallium/docs/source/screen.rst +++ b/src/gallium/docs/source/screen.rst @@ -6,4 +6,34 @@ A screen is an object representing the context-independent part of a device. Methods ------- -XXX +XXX moar; got bored + +get_name +^^^^^^^^ + +Returns an identifying name for the screen. + +get_vendor +^^^^^^^^^^ + +Returns the screen vendor. + +get_param +^^^^^^^^^ + +Get an integer/boolean screen parameter. + +get_paramf +^^^^^^^^^^ + +Get a floating-point screen parameter. + +is_format_supported +^^^^^^^^^^^^^^^^^^^ + +See if a format can be used in a specific manner. + +texture_create +^^^^^^^^^^^^^^ + +Given a template of texture setup, create a BO-backed texture. -- cgit v1.2.3