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