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