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