src/gallium/docs/source/context.rst

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