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