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
  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_sample_mask``
  58 * ``set_clip_state``
  59 * ``set_polygon_stipple``
  60 * ``set_scissor_state`` sets the bounds for the scissor test, which culls
  61   pixels before blending to render targets. If the :ref:`Rasterizer` does
  62   not have the scissor test enabled, then the scissor bounds never need to
  63   be set since they will not be used.
  64 * ``set_viewport_state``
  65
  66
  67 Sampler Views
  68 ^^^^^^^^^^^^^
  69
  70 These are the means to bind textures to shader stages. To create one, specify
  71 its format, swizzle and LOD range in sampler view template.
  72
  73 If texture format is different than template format, it is said the texture
  74 is being cast to another format. Casting can be done only between compatible
  75 formats, that is formats that have matching component order and sizes.
  76
  77 Swizzle fields specify they way in which fetched texel components are placed
  78 in the result register. For example, ``swizzle_r`` specifies what is going to be
  79 placed in first component of result register.
  80
  81 The ``first_level`` and ``last_level`` fields of sampler view template specify
  82 the LOD range the texture is going to be constrained to.
  83
  84 * ``set_fragment_sampler_views`` binds an array of sampler views to
  85   fragment shader stage. Every binding point acquires a reference
  86   to a respective sampler view and releases a reference to the previous
  87   sampler view.
  88
  89 * ``set_vertex_sampler_views`` binds an array of sampler views to vertex
  90   shader stage. Every binding point acquires a reference to a respective
  91   sampler view and releases a reference to the previous sampler view.
  92
  93 * ``create_sampler_view`` creates a new sampler view. ``texture`` is associated
  94   with the sampler view which results in sampler view holding a reference
  95   to the texture. Format specified in template must be compatible
  96   with texture format.
  97
  98 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
  99   to associated texture.
 100
 101
 102 Clearing
 103 ^^^^^^^^
 104
 105 Clear is one of the most difficult concepts to nail down to a single
 106 interface (due to both different requirements from APIs and also driver/hw
 107 specific differences).
 108
 109 ``clear`` initializes some or all of the surfaces currently bound to
 110 the framebuffer to particular RGBA, depth, or stencil values.
 111 Currently, this does not take into account color or stencil write masks (as
 112 used by GL), and always clears the whole surfaces (no scissoring as used by
 113 GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
 114 only depth or stencil in a combined depth/stencil surface, if the driver
 115 supports PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE.
 116 If a surface includes several layers/slices (XXX: not yet...) then all layers
 117 will be cleared.
 118
 119 ``clear_render_target`` clears a single color rendertarget with the specified
 120 color value. While it is only possible to clear one surface at a time (which can
 121 include several layers), this surface need not be bound to the framebuffer.
 122
 123 ``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface
 124 with the specified depth and stencil values (for combined depth/stencil buffers,
 125 is is also possible to only clear one or the other part). While it is only
 126 possible to clear one surface at a time (which can include several layers),
 127 this surface need not be bound to the framebuffer.
 128
 129
 130 Drawing
 131 ^^^^^^^
 132
 133 ``draw_arrays`` draws a specified primitive.
 134
 135 This command is equivalent to calling ``draw_arrays_instanced``
 136 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
 137
 138 ``draw_elements`` draws a specified primitive using an optional
 139 index buffer.
 140
 141 This command is equivalent to calling ``draw_elements_instanced``
 142 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
 143
 144 ``draw_range_elements``
 145
 146 XXX: this is (probably) a temporary entrypoint, as the range
 147 information should be available from the vertex_buffer state.
 148 Using this to quickly evaluate a specialized path in the draw
 149 module.
 150
 151 ``draw_arrays_instanced`` draws multiple instances of the same primitive.
 152
 153 This command is equivalent to calling ``draw_elements_instanced``
 154 with ``indexBuffer`` set to NULL and ``indexSize`` set to 0.
 155
 156 ``draw_elements_instanced`` draws multiple instances of the same primitive
 157 using an optional index buffer.
 158
 159 For instanceID in the range between ``startInstance``
 160 and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive
 161 specified by ``mode`` and sequential numbers in the range between ``start``
 162 and ``start``+``count``-1, inclusive.
 163
 164 If ``indexBuffer`` is not NULL, it specifies an index buffer with index
 165 byte size of ``indexSize``. The sequential numbers are used to lookup
 166 the index buffer and the resulting indices in turn are used to fetch
 167 vertex attributes.
 168
 169 If ``indexBuffer`` is NULL, the sequential numbers are used directly
 170 as indices to fetch vertex attributes.
 171
 172 ``indexBias`` is a value which is added to every index read from the index
 173 buffer before fetching vertex attributes.
 174
 175 ``minIndex`` and ``maxIndex`` describe minimum and maximum index contained in
 176 the index buffer.
 177
 178 If a given vertex element has ``instance_divisor`` set to 0, it is said
 179 it contains per-vertex data and effective vertex attribute address needs
 180 to be recalculated for every index.
 181
 182   attribAddr = ``stride`` * index + ``src_offset``
 183
 184 If a given vertex element has ``instance_divisor`` set to non-zero,
 185 it is said it contains per-instance data and effective vertex attribute
 186 address needs to recalculated for every ``instance_divisor``-th instance.
 187
 188   attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
 189
 190 In the above formulas, ``src_offset`` is taken from the given vertex element
 191 and ``stride`` is taken from a vertex buffer associated with the given
 192 vertex element.
 193
 194 The calculated attribAddr is used as an offset into the vertex buffer to
 195 fetch the attribute data.
 196
 197 The value of ``instanceID`` can be read in a vertex shader through a system
 198 value register declared with INSTANCEID semantic name.
 199
 200
 201 Queries
 202 ^^^^^^^
 203
 204 Queries gather some statistic from the 3D pipeline over one or more
 205 draws.  Queries may be nested, though no state tracker currently
 206 exercises this.
 207
 208 Queries can be created with ``create_query`` and deleted with
 209 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
 210 use ``end_query`` to end the query.
 211
 212 ``get_query_result`` is used to retrieve the results of a query.  If
 213 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
 214 will block until the results of the query are ready (and TRUE will be
 215 returned).  Otherwise, if the ``wait`` parameter is FALSE, the call
 216 will not block and the return value will be TRUE if the query has
 217 completed or FALSE otherwise.
 218
 219 The most common type of query is the occlusion query,
 220 ``PIPE_QUERY_OCCLUSION_COUNTER``, which counts the number of fragments which
 221 are written to the framebuffer without being culled by
 222 :ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions.
 223
 224 Another type of query, ``PIPE_QUERY_TIME_ELAPSED``, returns the amount of
 225 time, in nanoseconds, the context takes to perform operations.
 226
 227 Gallium does not guarantee the availability of any query types; one must
 228 always check the capabilities of the :ref:`Screen` first.
 229
 230
 231 Conditional Rendering
 232 ^^^^^^^^^^^^^^^^^^^^^
 233
 234 A drawing command can be skipped depending on the outcome of a query
 235 (typically an occlusion query).  The ``render_condition`` function specifies
 236 the query which should be checked prior to rendering anything.
 237
 238 If ``render_condition`` is called with ``query`` = NULL, conditional
 239 rendering is disabled and drawing takes place normally.
 240
 241 If ``render_condition`` is called with a non-null ``query`` subsequent
 242 drawing commands will be predicated on the outcome of the query.  If
 243 the query result is zero subsequent drawing commands will be skipped.
 244
 245 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
 246 query to complete before deciding whether to render.
 247
 248 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
 249 completed, the drawing command will be executed normally.  If the query
 250 has completed, drawing will be predicated on the outcome of the query.
 251
 252 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
 253 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
 254 for the non-REGION modes but in the case that an occulusion query returns
 255 a non-zero result, regions which were occluded may be ommitted by subsequent
 256 drawing commands.  This can result in better performance with some GPUs.
 257 Normally, if the occlusion query returned a non-zero result subsequent
 258 drawing happens normally so fragments may be generated, shaded and
 259 processed even where they're known to be obscured.
 260
 261
 262 Flushing
 263 ^^^^^^^^
 264
 265 ``flush``
 266
 267
 268 Resource Busy Queries
 269 ^^^^^^^^^^^^^^^^^^^^^
 270
 271 ``is_resource_referenced``
 272
 273
 274
 275 Blitting
 276 ^^^^^^^^
 277
 278 These methods emulate classic blitter controls.
 279
 280 These methods operate directly on ``pipe_resource`` objects, and stand
 281 apart from any 3D state in the context.  Blitting functionality may be
 282 moved to a separate abstraction at some point in the future.
 283
 284 ``resource_copy_region`` blits a region of a subresource of a resource to a
 285 region of another subresource of a resource, provided that both resources have the
 286 same format. The source and destination may be the same resource, but overlapping
 287 blits are not permitted.
 288
 289 ``resource_resolve`` resolves a multisampled resource into a non-multisampled
 290 one. Formats and dimensions must match. This function must be present if a driver
 291 supports multisampling.
 292
 293 The interfaces to these calls are likely to change to make it easier
 294 for a driver to batch multiple blits with the same source and
 295 destination.
 296
 297
 298 Stream Output
 299 ^^^^^^^^^^^^^
 300
 301 Stream output, also known as transform feedback allows writing the results of the
 302 vertex pipeline (after the geometry shader or vertex shader if no geometry shader
 303 is present) to be written to a buffer created with a ``PIPE_BIND_STREAM_OUTPUT``
 304 flag.
 305
 306 First a stream output state needs to be created with the
 307 ``create_stream_output_state`` call. It specific the details of what's being written,
 308 to which buffer and with what kind of a writemask.
 309
 310 Then target buffers needs to be set with the call to ``set_stream_output_buffers``
 311 which sets the buffers and the offsets from the start of those buffer to where
 312 the data will be written to.
 313
 314
 315 Transfers
 316 ^^^^^^^^^
 317
 318 These methods are used to get data to/from a resource.
 319
 320 ``get_transfer`` creates a transfer object.
 321
 322 ``transfer_destroy`` destroys the transfer object. May cause
 323 data to be written to the resource at this point.
 324
 325 ``transfer_map`` creates a memory mapping for the transfer object.
 326 The returned map points to the start of the mapped range according to
 327 the box region, not the beginning of the resource.
 328
 329 ``transfer_unmap`` remove the memory mapping for the transfer object.
 330 Any pointers into the map should be considered invalid and discarded.
 331
 332 ``transfer_inline_write`` performs a simplified transfer for simple writes.
 333 Basically get_transfer, transfer_map, data write, transfer_unmap, and
 334 transfer_destroy all in one.
 335
 336 .. _transfer_flush_region:
 337
 338 transfer_flush_region
 339 %%%%%%%%%%%%%%%%%%%%%
 340
 341 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
 342 be flushed on write or unmap. Flushes must be requested with
 343 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
 344 the beginning of the resource.
 345
 346 .. _pipe_transfer:
 347
 348 PIPE_TRANSFER
 349 ^^^^^^^^^^^^^
 350
 351 These flags control the behavior of a transfer object.
 352
 353 * ``READ``: resource contents are read at transfer create time.
 354 * ``WRITE``: resource contents will be written back at transfer destroy time.
 355 * ``MAP_DIRECTLY``: a transfer should directly map the resource. May return
 356   NULL if not supported.
 357 * ``DISCARD``: The memory within the mapped region is discarded.
 358   Cannot be used with ``READ``.
 359 * ``DONTBLOCK``: Fail if the resource cannot be mapped immediately.
 360 * ``UNSYNCHRONIZED``: Do not synchronize pending operations on the resource
 361   when mapping. The interaction of any writes to the map and any
 362   operations pending on the resource are undefined. Cannot be used with
 363   ``READ``.
 364 * ``FLUSH_EXPLICIT``: Written ranges will be notified later with
 365   :ref:`transfer_flush_region`. Cannot be used with ``READ``.