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_fragment_sampler_views`` binds an array of sampler views to
  45   fragment shader stage. Every binding point acquires a reference
  46   to a respective sampler view and releases a reference to the previous
  47   sampler view.
  48
  49 * ``set_vertex_sampler_views`` binds an array of sampler views to vertex
  50   shader stage. Every binding point acquires a reference to a respective
  51   sampler view and releases a reference to the previous sampler view.
  52
  53 * ``create_sampler_view`` creates a new sampler view. texture is associated
  54   with the sampler view which results in sampler view holding a reference
  55   to the texture. Format specified in template must be compatible
  56   with texture format.
  57
  58 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
  59   to associated texture.
  60
  61 * ``set_vertex_buffers``
  62
  63
  64 Non-CSO State
  65 ^^^^^^^^^^^^^
  66
  67 These pieces of state are too small, variable, and/or trivial to have CSO
  68 objects. They all follow simple, one-method binding calls, e.g.
  69 ``set_blend_color``.
  70 * ``set_stencil_ref`` sets the stencil front and back reference values
  71   which are used as comparison values in stencil test.
  72 * ``set_blend_color``
  73 * ``set_clip_state``
  74 * ``set_polygon_stipple``
  75 * ``set_scissor_state`` sets the bounds for the scissor test, which culls
  76   pixels before blending to render targets. If the :ref:`Rasterizer` does
  77   not have the scissor test enabled, then the scissor bounds never need to
  78   be set since they will not be used.
  79 * ``set_viewport_state``
  80
  81
  82 Clearing
  83 ^^^^^^^^
  84
  85 ``clear`` initializes some or all of the surfaces currently bound to
  86 the framebuffer to particular RGBA, depth, or stencil values.
  87
  88 Clear is one of the most difficult concepts to nail down to a single
  89 interface and it seems likely that we will want to add additional
  90 clear paths, for instance clearing surfaces not bound to the
  91 framebuffer, or read-modify-write clears such as depth-only or
  92 stencil-only clears of packed depth-stencil buffers.
  93
  94
  95 Drawing
  96 ^^^^^^^
  97
  98 ``draw_arrays`` draws a specified primitive.
  99
 100 This command is equivalent to calling ``draw_arrays_instanced``
 101 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
 102
 103 ``draw_elements`` draws a specified primitive using an optional
 104 index buffer.
 105
 106 This command is equivalent to calling ``draw_elements_instanced``
 107 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
 108
 109 ``draw_range_elements``
 110
 111 XXX: this is (probably) a temporary entrypoint, as the range
 112 information should be available from the vertex_buffer state.
 113 Using this to quickly evaluate a specialized path in the draw
 114 module.
 115
 116 ``draw_arrays_instanced`` draws multiple instances of the same primitive.
 117
 118 This command is equivalent to calling ``draw_elements_instanced``
 119 with ``indexBuffer`` set to NULL and ``indexSize`` set to 0.
 120
 121 ``draw_elements_instanced`` draws multiple instances of the same primitive
 122 using an optional index buffer.
 123
 124 For instanceID in the range between ``startInstance``
 125 and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive
 126 specified by ``mode`` and sequential numbers in the range between ``start``
 127 and ``start``+``count``-1, inclusive.
 128
 129 If ``indexBuffer`` is not NULL, it specifies an index buffer with index
 130 byte size of ``indexSize``. The sequential numbers are used to lookup
 131 the index buffer and the resulting indices in turn are used to fetch
 132 vertex attributes.
 133
 134 If ``indexBuffer`` is NULL, the sequential numbers are used directly
 135 as indices to fetch vertex attributes.
 136
 137 If a given vertex element has ``instance_divisor`` set to 0, it is said
 138 it contains per-vertex data and effective vertex attribute address needs
 139 to be recalculated for every index.
 140
 141   attribAddr = ``stride`` * index + ``src_offset``
 142
 143 If a given vertex element has ``instance_divisor`` set to non-zero,
 144 it is said it contains per-instance data and effective vertex attribute
 145 address needs to recalculated for every ``instance_divisor``-th instance.
 146
 147   attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
 148
 149 In the above formulas, ``src_offset`` is taken from the given vertex element
 150 and ``stride`` is taken from a vertex buffer associated with the given
 151 vertex element.
 152
 153 The calculated attribAddr is used as an offset into the vertex buffer to
 154 fetch the attribute data.
 155
 156 The value of ``instanceID`` can be read in a vertex shader through a system
 157 value register declared with INSTANCEID semantic name.
 158
 159
 160 Queries
 161 ^^^^^^^
 162
 163 Queries gather some statistic from the 3D pipeline over one or more
 164 draws.  Queries may be nested, though no state tracker currently
 165 exercises this.
 166
 167 Queries can be created with ``create_query`` and deleted with
 168 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
 169 use ``end_query`` to end the query.
 170
 171 ``get_query_result`` is used to retrieve the results of a query.  If
 172 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
 173 will block until the results of the query are ready (and TRUE will be
 174 returned).  Otherwise, if the ``wait`` parameter is FALSE, the call
 175 will not block and the return value will be TRUE if the query has
 176 completed or FALSE otherwise.
 177
 178 A common type of query is the occlusion query which counts the number of
 179 fragments/pixels which are written to the framebuffer (and not culled by
 180 Z/stencil/alpha testing or shader KILL instructions).
 181
 182
 183 Conditional Rendering
 184 ^^^^^^^^^^^^^^^^^^^^^
 185
 186 A drawing command can be skipped depending on the outcome of a query
 187 (typically an occlusion query).  The ``render_condition`` function specifies
 188 the query which should be checked prior to rendering anything.
 189
 190 If ``render_condition`` is called with ``query`` = NULL, conditional
 191 rendering is disabled and drawing takes place normally.
 192
 193 If ``render_condition`` is called with a non-null ``query`` subsequent
 194 drawing commands will be predicated on the outcome of the query.  If
 195 the query result is zero subsequent drawing commands will be skipped.
 196
 197 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
 198 query to complete before deciding whether to render.
 199
 200 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
 201 completed, the drawing command will be executed normally.  If the query
 202 has completed, drawing will be predicated on the outcome of the query.
 203
 204 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
 205 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
 206 for the non-REGION modes but in the case that an occulusion query returns
 207 a non-zero result, regions which were occluded may be ommitted by subsequent
 208 drawing commands.  This can result in better performance with some GPUs.
 209 Normally, if the occlusion query returned a non-zero result subsequent
 210 drawing happens normally so fragments may be generated, shaded and
 211 processed even where they're known to be obscured.
 212
 213
 214 Flushing
 215 ^^^^^^^^
 216
 217 ``flush``
 218
 219
 220 Resource Busy Queries
 221 ^^^^^^^^^^^^^^^^^^^^^
 222
 223 ``is_texture_referenced``
 224
 225 ``is_buffer_referenced``
 226
 227
 228
 229 Blitting
 230 ^^^^^^^^
 231
 232 These methods emulate classic blitter controls. They are not guaranteed to be
 233 available; if they are set to NULL, then they are not present.
 234
 235 These methods operate directly on ``pipe_surface`` objects, and stand
 236 apart from any 3D state in the context.  Blitting functionality may be
 237 moved to a separate abstraction at some point in the future.
 238
 239 ``surface_fill`` performs a fill operation on a section of a surface.
 240
 241 ``surface_copy`` blits a region of a surface to a region of another surface,
 242 provided that both surfaces are the same format. The source and destination
 243 may be the same surface, and overlapping blits are permitted.
 244
 245 The interfaces to these calls are likely to change to make it easier
 246 for a driver to batch multiple blits with the same source and
 247 destination.
 248