src/gallium/docs/source/context.rst

   1 Context
   2 =======
   3
   4 The context object represents the purest, most directly accessible, abilities
   5 of the device's 3D rendering pipeline.
   6
   7 Methods
   8 -------
   9
  10 CSO State
  11 ^^^^^^^^^
  12
  13 All CSO state is created, bound, and destroyed, with triplets of methods that
  14 all follow a specific naming scheme. For example, ``create_blend_state``,
  15 ``bind_blend_state``, and ``destroy_blend_state``.
  16
  17 CSO objects handled by the context object:
  18
  19 * :ref:`Blend`: ``*_blend_state``
  20 * :ref:`Sampler`: These are special; they can be bound to either vertex or
  21   fragment samplers, and they are bound in groups.
  22   ``bind_fragment_sampler_states``, ``bind_vertex_sampler_states``
  23 * :ref:`Rasterizer`: ``*_rasterizer_state``
  24 * :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state``
  25 * :ref:`Shader`: These have two sets of methods. ``*_fs_state`` is for
  26   fragment shaders, and ``*_vs_state`` is for vertex shaders.
  27 * :ref:`Vertex Elements`: ``*_vertex_elements_state``
  28
  29
  30 Resource Binding State
  31 ^^^^^^^^^^^^^^^^^^^^^^
  32
  33 This state describes how resources in various flavours (textures,
  34 buffers, surfaces) are bound to the driver.
  35
  36
  37 * ``set_constant_buffer`` sets a constant buffer to be used for a given shader
  38   type. index is used to indicate which buffer to set (some apis may allow
  39   multiple ones to be set, and binding a specific one later, though drivers
  40   are mostly restricted to the first one right now).
  41
  42 * ``set_framebuffer_state``
  43
  44 * ``set_vertex_buffers``
  45
  46
  47 Non-CSO State
  48 ^^^^^^^^^^^^^
  49
  50 These pieces of state are too small, variable, and/or trivial to have CSO
  51 objects. They all follow simple, one-method binding calls, e.g.
  52 ``set_blend_color``.
  53 * ``set_stencil_ref`` sets the stencil front and back reference values
  54   which are used as comparison values in stencil test.
  55 * ``set_blend_color``
  56 * ``set_clip_state``
  57 * ``set_polygon_stipple``
  58 * ``set_scissor_state`` sets the bounds for the scissor test, which culls
  59   pixels before blending to render targets. If the :ref:`Rasterizer` does
  60   not have the scissor test enabled, then the scissor bounds never need to
  61   be set since they will not be used.
  62 * ``set_viewport_state``
  63
  64
  65 Sampler Views
  66 ^^^^^^^^^^^^^
  67
  68 These are the means to bind textures to shader stages. To create one, specify
  69 its format, swizzle and LOD range in sampler view template.
  70
  71 If texture format is different than template format, it is said the texture
  72 is being cast to another format. Casting can be done only between compatible
  73 formats, that is formats that have matching component order and sizes.
  74
  75 Swizzle fields specify they way in which fetched texel components are placed
  76 in the result register. For example, swizzle_r specifies what is going to be
  77 placed in destination register x (AKA r).
  78
  79 first_level and last_level fields of sampler view template specify the LOD
  80 range the texture is going to be constrained to.
  81
  82 * ``set_fragment_sampler_views`` binds an array of sampler views to
  83   fragment shader stage. Every binding point acquires a reference
  84   to a respective sampler view and releases a reference to the previous
  85   sampler view.
  86
  87 * ``set_vertex_sampler_views`` binds an array of sampler views to vertex
  88   shader stage. Every binding point acquires a reference to a respective
  89   sampler view and releases a reference to the previous sampler view.
  90
  91 * ``create_sampler_view`` creates a new sampler view. texture is associated
  92   with the sampler view which results in sampler view holding a reference
  93   to the texture. Format specified in template must be compatible
  94   with texture format.
  95
  96 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
  97   to associated texture.
  98
  99
 100 Clearing
 101 ^^^^^^^^
 102
 103 ``clear`` initializes some or all of the surfaces currently bound to
 104 the framebuffer to particular RGBA, depth, or stencil values.
 105
 106 Clear is one of the most difficult concepts to nail down to a single
 107 interface and it seems likely that we will want to add additional
 108 clear paths, for instance clearing surfaces not bound to the
 109 framebuffer, or read-modify-write clears such as depth-only or
 110 stencil-only clears of packed depth-stencil buffers.
 111
 112
 113 Drawing
 114 ^^^^^^^
 115
 116 ``draw_arrays`` draws a specified primitive.
 117
 118 This command is equivalent to calling ``draw_arrays_instanced``
 119 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
 120
 121 ``draw_elements`` draws a specified primitive using an optional
 122 index buffer.
 123
 124 This command is equivalent to calling ``draw_elements_instanced``
 125 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
 126
 127 ``draw_range_elements``
 128
 129 XXX: this is (probably) a temporary entrypoint, as the range
 130 information should be available from the vertex_buffer state.
 131 Using this to quickly evaluate a specialized path in the draw
 132 module.
 133
 134 ``draw_arrays_instanced`` draws multiple instances of the same primitive.
 135
 136 This command is equivalent to calling ``draw_elements_instanced``
 137 with ``indexBuffer`` set to NULL and ``indexSize`` set to 0.
 138
 139 ``draw_elements_instanced`` draws multiple instances of the same primitive
 140 using an optional index buffer.
 141
 142 For instanceID in the range between ``startInstance``
 143 and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive
 144 specified by ``mode`` and sequential numbers in the range between ``start``
 145 and ``start``+``count``-1, inclusive.
 146
 147 If ``indexBuffer`` is not NULL, it specifies an index buffer with index
 148 byte size of ``indexSize``. The sequential numbers are used to lookup
 149 the index buffer and the resulting indices in turn are used to fetch
 150 vertex attributes.
 151
 152 If ``indexBuffer`` is NULL, the sequential numbers are used directly
 153 as indices to fetch vertex attributes.
 154
 155 If a given vertex element has ``instance_divisor`` set to 0, it is said
 156 it contains per-vertex data and effective vertex attribute address needs
 157 to be recalculated for every index.
 158
 159   attribAddr = ``stride`` * index + ``src_offset``
 160
 161 If a given vertex element has ``instance_divisor`` set to non-zero,
 162 it is said it contains per-instance data and effective vertex attribute
 163 address needs to recalculated for every ``instance_divisor``-th instance.
 164
 165   attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
 166
 167 In the above formulas, ``src_offset`` is taken from the given vertex element
 168 and ``stride`` is taken from a vertex buffer associated with the given
 169 vertex element.
 170
 171 The calculated attribAddr is used as an offset into the vertex buffer to
 172 fetch the attribute data.
 173
 174 The value of ``instanceID`` can be read in a vertex shader through a system
 175 value register declared with INSTANCEID semantic name.
 176
 177
 178 Queries
 179 ^^^^^^^
 180
 181 Queries gather some statistic from the 3D pipeline over one or more
 182 draws.  Queries may be nested, though no state tracker currently
 183 exercises this.
 184
 185 Queries can be created with ``create_query`` and deleted with
 186 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
 187 use ``end_query`` to end the query.
 188
 189 ``get_query_result`` is used to retrieve the results of a query.  If
 190 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
 191 will block until the results of the query are ready (and TRUE will be
 192 returned).  Otherwise, if the ``wait`` parameter is FALSE, the call
 193 will not block and the return value will be TRUE if the query has
 194 completed or FALSE otherwise.
 195
 196 A common type of query is the occlusion query which counts the number of
 197 fragments/pixels which are written to the framebuffer (and not culled by
 198 Z/stencil/alpha testing or shader KILL instructions).
 199
 200
 201 Conditional Rendering
 202 ^^^^^^^^^^^^^^^^^^^^^
 203
 204 A drawing command can be skipped depending on the outcome of a query
 205 (typically an occlusion query).  The ``render_condition`` function specifies
 206 the query which should be checked prior to rendering anything.
 207
 208 If ``render_condition`` is called with ``query`` = NULL, conditional
 209 rendering is disabled and drawing takes place normally.
 210
 211 If ``render_condition`` is called with a non-null ``query`` subsequent
 212 drawing commands will be predicated on the outcome of the query.  If
 213 the query result is zero subsequent drawing commands will be skipped.
 214
 215 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
 216 query to complete before deciding whether to render.
 217
 218 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
 219 completed, the drawing command will be executed normally.  If the query
 220 has completed, drawing will be predicated on the outcome of the query.
 221
 222 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
 223 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
 224 for the non-REGION modes but in the case that an occulusion query returns
 225 a non-zero result, regions which were occluded may be ommitted by subsequent
 226 drawing commands.  This can result in better performance with some GPUs.
 227 Normally, if the occlusion query returned a non-zero result subsequent
 228 drawing happens normally so fragments may be generated, shaded and
 229 processed even where they're known to be obscured.
 230
 231
 232 Flushing
 233 ^^^^^^^^
 234
 235 ``flush``
 236
 237
 238 Resource Busy Queries
 239 ^^^^^^^^^^^^^^^^^^^^^
 240
 241 ``is_texture_referenced``
 242
 243 ``is_buffer_referenced``
 244
 245
 246
 247 Blitting
 248 ^^^^^^^^
 249
 250 These methods emulate classic blitter controls. They are not guaranteed to be
 251 available; if they are set to NULL, then they are not present.
 252
 253 These methods operate directly on ``pipe_surface`` objects, and stand
 254 apart from any 3D state in the context.  Blitting functionality may be
 255 moved to a separate abstraction at some point in the future.
 256
 257 ``surface_fill`` performs a fill operation on a section of a surface.
 258
 259 ``surface_copy`` blits a region of a surface to a region of another surface,
 260 provided that both surfaces are the same format. The source and destination
 261 may be the same surface, and overlapping blits are permitted.
 262
 263 The interfaces to these calls are likely to change to make it easier
 264 for a driver to batch multiple blits with the same source and
 265 destination.
 266