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