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`` initializes some or all of the surfaces currently bound to
 106 the framebuffer to particular RGBA, depth, or stencil values.
 107
 108 Clear is one of the most difficult concepts to nail down to a single
 109 interface and it seems likely that we will want to add additional
 110 clear paths, for instance clearing surfaces not bound to the
 111 framebuffer, or read-modify-write clears such as depth-only or
 112 stencil-only clears of packed depth-stencil buffers.
 113
 114
 115 Drawing
 116 ^^^^^^^
 117
 118 ``draw_arrays`` draws a specified primitive.
 119
 120 This command is equivalent to calling ``draw_arrays_instanced``
 121 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
 122
 123 ``draw_elements`` draws a specified primitive using an optional
 124 index buffer.
 125
 126 This command is equivalent to calling ``draw_elements_instanced``
 127 with ``startInstance`` set to 0 and ``instanceCount`` set to 1.
 128
 129 ``draw_range_elements``
 130
 131 XXX: this is (probably) a temporary entrypoint, as the range
 132 information should be available from the vertex_buffer state.
 133 Using this to quickly evaluate a specialized path in the draw
 134 module.
 135
 136 ``draw_arrays_instanced`` draws multiple instances of the same primitive.
 137
 138 This command is equivalent to calling ``draw_elements_instanced``
 139 with ``indexBuffer`` set to NULL and ``indexSize`` set to 0.
 140
 141 ``draw_elements_instanced`` draws multiple instances of the same primitive
 142 using an optional index buffer.
 143
 144 For instanceID in the range between ``startInstance``
 145 and ``startInstance``+``instanceCount``-1, inclusive, draw a primitive
 146 specified by ``mode`` and sequential numbers in the range between ``start``
 147 and ``start``+``count``-1, inclusive.
 148
 149 If ``indexBuffer`` is not NULL, it specifies an index buffer with index
 150 byte size of ``indexSize``. The sequential numbers are used to lookup
 151 the index buffer and the resulting indices in turn are used to fetch
 152 vertex attributes.
 153
 154 If ``indexBuffer`` is NULL, the sequential numbers are used directly
 155 as indices to fetch vertex attributes.
 156
 157 ``indexBias`` is a value which is added to every index read from the index
 158 buffer before fetching vertex attributes.
 159
 160 ``minIndex`` and ``maxIndex`` describe minimum and maximum index contained in
 161 the index buffer.
 162
 163 If a given vertex element has ``instance_divisor`` set to 0, it is said
 164 it contains per-vertex data and effective vertex attribute address needs
 165 to be recalculated for every index.
 166
 167   attribAddr = ``stride`` * index + ``src_offset``
 168
 169 If a given vertex element has ``instance_divisor`` set to non-zero,
 170 it is said it contains per-instance data and effective vertex attribute
 171 address needs to recalculated for every ``instance_divisor``-th instance.
 172
 173   attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
 174
 175 In the above formulas, ``src_offset`` is taken from the given vertex element
 176 and ``stride`` is taken from a vertex buffer associated with the given
 177 vertex element.
 178
 179 The calculated attribAddr is used as an offset into the vertex buffer to
 180 fetch the attribute data.
 181
 182 The value of ``instanceID`` can be read in a vertex shader through a system
 183 value register declared with INSTANCEID semantic name.
 184
 185
 186 Queries
 187 ^^^^^^^
 188
 189 Queries gather some statistic from the 3D pipeline over one or more
 190 draws.  Queries may be nested, though no state tracker currently
 191 exercises this.
 192
 193 Queries can be created with ``create_query`` and deleted with
 194 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
 195 use ``end_query`` to end the query.
 196
 197 ``get_query_result`` is used to retrieve the results of a query.  If
 198 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
 199 will block until the results of the query are ready (and TRUE will be
 200 returned).  Otherwise, if the ``wait`` parameter is FALSE, the call
 201 will not block and the return value will be TRUE if the query has
 202 completed or FALSE otherwise.
 203
 204 The most common type of query is the occlusion query,
 205 ``PIPE_QUERY_OCCLUSION_COUNTER``, which counts the number of fragments which
 206 are written to the framebuffer without being culled by
 207 :ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions.
 208
 209 Another type of query, ``PIPE_QUERY_TIME_ELAPSED``, returns the amount of
 210 time, in nanoseconds, the context takes to perform operations.
 211
 212 Gallium does not guarantee the availability of any query types; one must
 213 always check the capabilities of the :ref:`Screen` first.
 214
 215
 216 Conditional Rendering
 217 ^^^^^^^^^^^^^^^^^^^^^
 218
 219 A drawing command can be skipped depending on the outcome of a query
 220 (typically an occlusion query).  The ``render_condition`` function specifies
 221 the query which should be checked prior to rendering anything.
 222
 223 If ``render_condition`` is called with ``query`` = NULL, conditional
 224 rendering is disabled and drawing takes place normally.
 225
 226 If ``render_condition`` is called with a non-null ``query`` subsequent
 227 drawing commands will be predicated on the outcome of the query.  If
 228 the query result is zero subsequent drawing commands will be skipped.
 229
 230 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
 231 query to complete before deciding whether to render.
 232
 233 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
 234 completed, the drawing command will be executed normally.  If the query
 235 has completed, drawing will be predicated on the outcome of the query.
 236
 237 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
 238 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
 239 for the non-REGION modes but in the case that an occulusion query returns
 240 a non-zero result, regions which were occluded may be ommitted by subsequent
 241 drawing commands.  This can result in better performance with some GPUs.
 242 Normally, if the occlusion query returned a non-zero result subsequent
 243 drawing happens normally so fragments may be generated, shaded and
 244 processed even where they're known to be obscured.
 245
 246
 247 Flushing
 248 ^^^^^^^^
 249
 250 ``flush``
 251
 252
 253 Resource Busy Queries
 254 ^^^^^^^^^^^^^^^^^^^^^
 255
 256 ``is_resource_referenced``
 257
 258
 259
 260 Blitting
 261 ^^^^^^^^
 262
 263 These methods emulate classic blitter controls.
 264
 265 These methods operate directly on ``pipe_resource`` objects, and stand
 266 apart from any 3D state in the context.  Blitting functionality may be
 267 moved to a separate abstraction at some point in the future.
 268
 269 ``resource_fill_region`` performs a fill operation on a section of a resource.
 270
 271 ``resource_copy_region`` blits a region of a subresource of a resource to a
 272 region of another subresource of a resource, provided that both resources have the
 273 same format. The source and destination may be the same resource, but overlapping
 274 blits are not permitted.
 275
 276 ``resource_resolve`` resolves a multisampled resource into a non-multisampled
 277 one. Formats and dimensions must match. This function must be present if a driver
 278 supports multisampling.
 279
 280 The interfaces to these calls are likely to change to make it easier
 281 for a driver to batch multiple blits with the same source and
 282 destination.
 283
 284
 285 Transfers
 286 ^^^^^^^^^
 287
 288 These methods are used to get data to/from a resource.
 289
 290 ``get_transfer`` creates a transfer object.
 291
 292 ``transfer_destroy`` destroys the transfer object. May cause
 293 data to be written to the resource at this point.
 294
 295 ``transfer_map`` creates a memory mapping for the transfer object.
 296 The returned map points to the start of the mapped range according to
 297 the box region, not the beginning of the resource.
 298
 299 ``transfer_unmap`` remove the memory mapping for the transfer object.
 300 Any pointers into the map should be considered invalid and discarded.
 301
 302 ``transfer_inline_write`` performs a simplified transfer for simple writes.
 303 Basically get_transfer, transfer_map, data write, transfer_unmap, and
 304 transfer_destroy all in one.
 305
 306 .. _transfer_flush_region:
 307
 308 transfer_flush_region
 309 %%%%%%%%%%%%%%%%%%%%%
 310
 311 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
 312 be flushed on write or unmap. Flushes must be requested with
 313 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
 314 the beginning of the resource.
 315
 316 .. _pipe_transfer:
 317
 318 PIPE_TRANSFER
 319 ^^^^^^^^^^^^^
 320
 321 These flags control the behavior of a transfer object.
 322
 323 * ``READ``: resource contents are read at transfer create time.
 324 * ``WRITE``: resource contents will be written back at transfer destroy time.
 325 * ``MAP_DIRECTLY``: a transfer should directly map the resource. May return
 326   NULL if not supported.
 327 * ``DISCARD``: The memory within the mapped region is discarded.
 328   Cannot be used with ``READ``.
 329 * ``DONTBLOCK``: Fail if the resource cannot be mapped immediately.
 330 * ``UNSYNCHRONIZED``: Do not synchronize pending operations on the resource
 331   when mapping. The interaction of any writes to the map and any
 332   operations pending on the resource are undefined. Cannot be used with
 333   ``READ``.
 334 * ``FLUSH_EXPLICIT``: Written ranges will be notified later with
 335   :ref:`transfer_flush_region`. Cannot be used with ``READ``.