gallium: add condition parameter to render_condition
[mesa.git] / src / gallium / docs / source / context.rst
1 .. _context:
2
3 Context
4 =======
5
6 A Gallium rendering context encapsulates the state which effects 3D
7 rendering such as blend state, depth/stencil state, texture samplers,
8 etc.
9
10 Note that resource/texture allocation is not per-context but per-screen.
11
12
13 Methods
14 -------
15
16 CSO State
17 ^^^^^^^^^
18
19 All Constant State Object (CSO) state is created, bound, and destroyed,
20 with triplets of methods that all follow a specific naming scheme.
21 For example, ``create_blend_state``, ``bind_blend_state``, and
22 ``destroy_blend_state``.
23
24 CSO objects handled by the context object:
25
26 * :ref:`Blend`: ``*_blend_state``
27 * :ref:`Sampler`: Texture sampler states are bound separately for fragment,
28 vertex and geometry samplers. Note that sampler states are set en masse.
29 If M is the max number of sampler units supported by the driver and N
30 samplers are bound with ``bind_fragment_sampler_states`` then sampler
31 units N..M-1 are considered disabled/NULL.
32 * :ref:`Rasterizer`: ``*_rasterizer_state``
33 * :ref:`Depth, Stencil, & Alpha`: ``*_depth_stencil_alpha_state``
34 * :ref:`Shader`: These are create, bind and destroy methods for vertex,
35 fragment and geometry shaders.
36 * :ref:`Vertex Elements`: ``*_vertex_elements_state``
37
38
39 Resource Binding State
40 ^^^^^^^^^^^^^^^^^^^^^^
41
42 This state describes how resources in various flavours (textures,
43 buffers, surfaces) are bound to the driver.
44
45
46 * ``set_constant_buffer`` sets a constant buffer to be used for a given shader
47 type. index is used to indicate which buffer to set (some apis may allow
48 multiple ones to be set, and binding a specific one later, though drivers
49 are mostly restricted to the first one right now).
50
51 * ``set_framebuffer_state``
52
53 * ``set_vertex_buffers``
54
55 * ``set_index_buffer``
56
57
58 Non-CSO State
59 ^^^^^^^^^^^^^
60
61 These pieces of state are too small, variable, and/or trivial to have CSO
62 objects. They all follow simple, one-method binding calls, e.g.
63 ``set_blend_color``.
64
65 * ``set_stencil_ref`` sets the stencil front and back reference values
66 which are used as comparison values in stencil test.
67 * ``set_blend_color``
68 * ``set_sample_mask``
69 * ``set_clip_state``
70 * ``set_polygon_stipple``
71 * ``set_scissor_states`` sets the bounds for the scissor test, which culls
72 pixels before blending to render targets. If the :ref:`Rasterizer` does
73 not have the scissor test enabled, then the scissor bounds never need to
74 be set since they will not be used. Note that scissor xmin and ymin are
75 inclusive, but xmax and ymax are exclusive. The inclusive ranges in x
76 and y would be [xmin..xmax-1] and [ymin..ymax-1]. The number of scissors
77 should be the same as the number of set viewports and can be up to
78 PIPE_MAX_VIEWPORTS.
79 * ``set_viewport_states``
80
81
82 Sampler Views
83 ^^^^^^^^^^^^^
84
85 These are the means to bind textures to shader stages. To create one, specify
86 its format, swizzle and LOD range in sampler view template.
87
88 If texture format is different than template format, it is said the texture
89 is being cast to another format. Casting can be done only between compatible
90 formats, that is formats that have matching component order and sizes.
91
92 Swizzle fields specify they way in which fetched texel components are placed
93 in the result register. For example, ``swizzle_r`` specifies what is going to be
94 placed in first component of result register.
95
96 The ``first_level`` and ``last_level`` fields of sampler view template specify
97 the LOD range the texture is going to be constrained to. Note that these
98 values are in addition to the respective min_lod, max_lod values in the
99 pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip
100 level used for sampling from the resource is effectively the fifth).
101
102 The ``first_layer`` and ``last_layer`` fields specify the layer range the
103 texture is going to be constrained to. Similar to the LOD range, this is added
104 to the array index which is used for sampling.
105
106 * ``set_fragment_sampler_views`` binds an array of sampler views to
107 fragment shader stage. Every binding point acquires a reference
108 to a respective sampler view and releases a reference to the previous
109 sampler view. If M is the maximum number of sampler units and N units
110 is passed to set_fragment_sampler_views, the driver should unbind the
111 sampler views for units N..M-1.
112
113 * ``set_vertex_sampler_views`` binds an array of sampler views to vertex
114 shader stage. Every binding point acquires a reference to a respective
115 sampler view and releases a reference to the previous sampler view.
116
117 * ``create_sampler_view`` creates a new sampler view. ``texture`` is associated
118 with the sampler view which results in sampler view holding a reference
119 to the texture. Format specified in template must be compatible
120 with texture format.
121
122 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
123 to associated texture.
124
125 Shader Resources
126 ^^^^^^^^^^^^^^^^
127
128 Shader resources are textures or buffers that may be read or written
129 from a shader without an associated sampler. This means that they
130 have no support for floating point coordinates, address wrap modes or
131 filtering.
132
133 Shader resources are specified for all the shader stages at once using
134 the ``set_shader_resources`` method. When binding texture resources,
135 the ``level``, ``first_layer`` and ``last_layer`` pipe_surface fields
136 specify the mipmap level and the range of layers the texture will be
137 constrained to. In the case of buffers, ``first_element`` and
138 ``last_element`` specify the range within the buffer that will be used
139 by the shader resource. Writes to a shader resource are only allowed
140 when the ``writable`` flag is set.
141
142 Surfaces
143 ^^^^^^^^
144
145 These are the means to use resources as color render targets or depthstencil
146 attachments. To create one, specify the mip level, the range of layers, and
147 the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET).
148 Note that layer values are in addition to what is indicated by the geometry
149 shader output variable XXX_FIXME (that is if first_layer is 3 and geometry
150 shader indicates index 2, the 5th layer of the resource will be used). These
151 first_layer and last_layer parameters will only be used for 1d array, 2d array,
152 cube, and 3d textures otherwise they are 0.
153
154 * ``create_surface`` creates a new surface.
155
156 * ``surface_destroy`` destroys a surface and releases its reference to the
157 associated resource.
158
159 Stream output targets
160 ^^^^^^^^^^^^^^^^^^^^^
161
162 Stream output, also known as transform feedback, allows writing the primitives
163 produced by the vertex pipeline to buffers. This is done after the geometry
164 shader or vertex shader if no geometry shader is present.
165
166 The stream output targets are views into buffer resources which can be bound
167 as stream outputs and specify a memory range where it's valid to write
168 primitives. The pipe driver must implement memory protection such that any
169 primitives written outside of the specified memory range are discarded.
170
171 Two stream output targets can use the same resource at the same time, but
172 with a disjoint memory range.
173
174 Additionally, the stream output target internally maintains the offset
175 into the buffer which is incremented everytime something is written to it.
176 The internal offset is equal to how much data has already been written.
177 It can be stored in device memory and the CPU actually doesn't have to query
178 it.
179
180 The stream output target can be used in a draw command to provide
181 the vertex count. The vertex count is derived from the internal offset
182 discussed above.
183
184 * ``create_stream_output_target`` create a new target.
185
186 * ``stream_output_target_destroy`` destroys a target. Users of this should
187 use pipe_so_target_reference instead.
188
189 * ``set_stream_output_targets`` binds stream output targets. The parameter
190 append_bitmask is a bitmask, where the i-th bit specifies whether new
191 primitives should be appended to the i-th buffer (writing starts at
192 the internal offset), or whether writing should start at the beginning
193 (the internal offset is effectively set to 0).
194
195 NOTE: The currently-bound vertex or geometry shader must be compiled with
196 the properly-filled-in structure pipe_stream_output_info describing which
197 outputs should be written to buffers and how. The structure is part of
198 pipe_shader_state.
199
200 Clearing
201 ^^^^^^^^
202
203 Clear is one of the most difficult concepts to nail down to a single
204 interface (due to both different requirements from APIs and also driver/hw
205 specific differences).
206
207 ``clear`` initializes some or all of the surfaces currently bound to
208 the framebuffer to particular RGBA, depth, or stencil values.
209 Currently, this does not take into account color or stencil write masks (as
210 used by GL), and always clears the whole surfaces (no scissoring as used by
211 GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
212 only depth or stencil in a combined depth/stencil surface.
213 If a surface includes several layers then all layers will be cleared.
214
215 ``clear_render_target`` clears a single color rendertarget with the specified
216 color value. While it is only possible to clear one surface at a time (which can
217 include several layers), this surface need not be bound to the framebuffer.
218
219 ``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface
220 with the specified depth and stencil values (for combined depth/stencil buffers,
221 is is also possible to only clear one or the other part). While it is only
222 possible to clear one surface at a time (which can include several layers),
223 this surface need not be bound to the framebuffer.
224
225
226 Drawing
227 ^^^^^^^
228
229 ``draw_vbo`` draws a specified primitive. The primitive mode and other
230 properties are described by ``pipe_draw_info``.
231
232 The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the
233 the mode of the primitive and the vertices to be fetched, in the range between
234 ``start`` to ``start``+``count``-1, inclusive.
235
236 Every instance with instanceID in the range between ``start_instance`` and
237 ``start_instance``+``instance_count``-1, inclusive, will be drawn.
238
239 If there is an index buffer bound, and ``indexed`` field is true, all vertex
240 indices will be looked up in the index buffer.
241
242 In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower
243 and upper bound of the indices contained in the index buffer inside the range
244 between ``start`` to ``start``+``count``-1. This allows the driver to
245 determine which subset of vertices will be referenced during te draw call
246 without having to scan the index buffer. Providing a over-estimation of the
247 the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and
248 0xffffffff respectively, must give exactly the same rendering, albeit with less
249 performance due to unreferenced vertex buffers being unnecessarily DMA'ed or
250 processed. Providing a underestimation of the true bounds will result in
251 undefined behavior, but should not result in program or system failure.
252
253 In case of non-indexed draw, ``min_index`` should be set to
254 ``start`` and ``max_index`` should be set to ``start``+``count``-1.
255
256 ``index_bias`` is a value added to every vertex index after lookup and before
257 fetching vertex attributes.
258
259 When drawing indexed primitives, the primitive restart index can be
260 used to draw disjoint primitive strips. For example, several separate
261 line strips can be drawn by designating a special index value as the
262 restart index. The ``primitive_restart`` flag enables/disables this
263 feature. The ``restart_index`` field specifies the restart index value.
264
265 When primitive restart is in use, array indexes are compared to the
266 restart index before adding the index_bias offset.
267
268 If a given vertex element has ``instance_divisor`` set to 0, it is said
269 it contains per-vertex data and effective vertex attribute address needs
270 to be recalculated for every index.
271
272 attribAddr = ``stride`` * index + ``src_offset``
273
274 If a given vertex element has ``instance_divisor`` set to non-zero,
275 it is said it contains per-instance data and effective vertex attribute
276 address needs to recalculated for every ``instance_divisor``-th instance.
277
278 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
279
280 In the above formulas, ``src_offset`` is taken from the given vertex element
281 and ``stride`` is taken from a vertex buffer associated with the given
282 vertex element.
283
284 The calculated attribAddr is used as an offset into the vertex buffer to
285 fetch the attribute data.
286
287 The value of ``instanceID`` can be read in a vertex shader through a system
288 value register declared with INSTANCEID semantic name.
289
290
291 Queries
292 ^^^^^^^
293
294 Queries gather some statistic from the 3D pipeline over one or more
295 draws. Queries may be nested, though not all state trackers exercise this.
296
297 Queries can be created with ``create_query`` and deleted with
298 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
299 use ``end_query`` to end the query.
300
301 ``get_query_result`` is used to retrieve the results of a query. If
302 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
303 will block until the results of the query are ready (and TRUE will be
304 returned). Otherwise, if the ``wait`` parameter is FALSE, the call
305 will not block and the return value will be TRUE if the query has
306 completed or FALSE otherwise.
307
308 The interface currently includes the following types of queries:
309
310 ``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which
311 are written to the framebuffer without being culled by
312 :ref:`Depth, Stencil, & Alpha` testing or shader KILL instructions.
313 The result is an unsigned 64-bit integer.
314 This query can be used with ``render_condition``.
315
316 In cases where a boolean result of an occlusion query is enough,
317 ``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like
318 ``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean
319 value of FALSE for cases where COUNTER would result in 0 and TRUE
320 for all other cases.
321 This query can be used with ``render_condition``.
322
323 ``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds,
324 the context takes to perform operations.
325 The result is an unsigned 64-bit integer.
326
327 ``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp,
328 scaled to nanoseconds, recorded after all commands issued prior to
329 ``end_query`` have been processed.
330 This query does not require a call to ``begin_query``.
331 The result is an unsigned 64-bit integer.
332
333 ``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check whether the
334 internal timer resolution is good enough to distinguish between the
335 events at ``begin_query`` and ``end_query``.
336 The result is a 64-bit integer specifying the timer resolution in Hz,
337 followed by a boolean value indicating whether the timer has incremented.
338
339 ``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating
340 the number of primitives processed by the pipeline (regardless of whether
341 stream output is active or not).
342
343 ``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating
344 the number of primitives written to stream output buffers.
345
346 ``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to
347 the result of
348 ``PIPE_QUERY_PRIMITIVES_EMITTED`` and
349 the number of primitives that would have been written to stream output buffers
350 if they had infinite space available (primitives_storage_needed), in this order.
351
352 ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating
353 whether the stream output targets have overflowed as a result of the
354 commands issued between ``begin_query`` and ``end_query``.
355 This query can be used with ``render_condition``.
356
357 ``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether
358 all commands issued before ``end_query`` have completed. However, this
359 does not imply serialization.
360 This query does not require a call to ``begin_query``.
361
362 ``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following
363 64-bit integers:
364 Number of vertices read from vertex buffers.
365 Number of primitives read from vertex buffers.
366 Number of vertex shader threads launched.
367 Number of geometry shader threads launched.
368 Number of primitives generated by geometry shaders.
369 Number of primitives forwarded to the rasterizer.
370 Number of primitives rasterized.
371 Number of fragment shader threads launched.
372 Number of tessellation control shader threads launched.
373 Number of tessellation evaluation shader threads launched.
374 If a shader type is not supported by the device/driver,
375 the corresponding values should be set to 0.
376
377 Gallium does not guarantee the availability of any query types; one must
378 always check the capabilities of the :ref:`Screen` first.
379
380
381 Conditional Rendering
382 ^^^^^^^^^^^^^^^^^^^^^
383
384 A drawing command can be skipped depending on the outcome of a query
385 (typically an occlusion query, or streamout overflow predicate).
386 The ``render_condition`` function specifies the query which should be checked
387 prior to rendering anything. Functions honoring render_condition include
388 (and are limited to) draw_vbo, clear, clear_render_target, clear_depth_stencil.
389
390 If ``render_condition`` is called with ``query`` = NULL, conditional
391 rendering is disabled and drawing takes place normally.
392
393 If ``render_condition`` is called with a non-null ``query`` subsequent
394 drawing commands will be predicated on the outcome of the query.
395 Commands will be skipped if ``condition`` is equal to the predicate result
396 (for non-boolean queries such as OCCLUSION_QUERY, zero counts as FALSE,
397 non-zero as TRUE).
398
399 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
400 query to complete before deciding whether to render.
401
402 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
403 completed, the drawing command will be executed normally. If the query
404 has completed, drawing will be predicated on the outcome of the query.
405
406 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
407 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
408 for the non-REGION modes but in the case that an occlusion query returns
409 a non-zero result, regions which were occluded may be ommitted by subsequent
410 drawing commands. This can result in better performance with some GPUs.
411 Normally, if the occlusion query returned a non-zero result subsequent
412 drawing happens normally so fragments may be generated, shaded and
413 processed even where they're known to be obscured.
414
415
416 Flushing
417 ^^^^^^^^
418
419 ``flush``
420
421
422 Resource Busy Queries
423 ^^^^^^^^^^^^^^^^^^^^^
424
425 ``is_resource_referenced``
426
427
428
429 Blitting
430 ^^^^^^^^
431
432 These methods emulate classic blitter controls.
433
434 These methods operate directly on ``pipe_resource`` objects, and stand
435 apart from any 3D state in the context. Blitting functionality may be
436 moved to a separate abstraction at some point in the future.
437
438 ``resource_copy_region`` blits a region of a resource to a region of another
439 resource, provided that both resources have the same format, or compatible
440 formats, i.e., formats for which copying the bytes from the source resource
441 unmodified to the destination resource will achieve the same effect of a
442 textured quad blitter.. The source and destination may be the same resource,
443 but overlapping blits are not permitted.
444 This can be considered the equivalent of a CPU memcpy.
445
446 ``blit`` blits a region of a resource to a region of another resource, including
447 scaling, format conversion, and up-/downsampling, as well as
448 a destination clip rectangle (scissors).
449 As opposed to manually drawing a textured quad, this lets the pipe driver choose
450 the optimal method for blitting (like using a special 2D engine), and usually
451 offers, for example, accelerated stencil-only copies even where
452 PIPE_CAP_SHADER_STENCIL_EXPORT is not available.
453
454
455 Transfers
456 ^^^^^^^^^
457
458 These methods are used to get data to/from a resource.
459
460 ``transfer_map`` creates a memory mapping and the transfer object
461 associated with it.
462 The returned pointer points to the start of the mapped range according to
463 the box region, not the beginning of the resource. If transfer_map fails,
464 the returned pointer to the buffer memory is NULL, and the pointer
465 to the transfer object remains unchanged (i.e. it can be non-NULL).
466
467 ``transfer_unmap`` remove the memory mapping for and destroy
468 the transfer object. The pointer into the resource should be considered
469 invalid and discarded.
470
471 ``transfer_inline_write`` performs a simplified transfer for simple writes.
472 Basically transfer_map, data write, and transfer_unmap all in one.
473
474
475 The box parameter to some of these functions defines a 1D, 2D or 3D
476 region of pixels. This is self-explanatory for 1D, 2D and 3D texture
477 targets.
478
479 For PIPE_TEXTURE_1D_ARRAY and PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth
480 fields refer to the array dimension of the texture.
481
482 For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the
483 faces of the cube map (z + depth <= 6).
484
485 For PIPE_TEXTURE_CUBE_ARRAY, the box:z and box::depth fields refer to both
486 the face and array dimension of the texture (face = z % 6, array = z / 6).
487
488
489 .. _transfer_flush_region:
490
491 transfer_flush_region
492 %%%%%%%%%%%%%%%%%%%%%
493
494 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
495 be flushed on write or unmap. Flushes must be requested with
496 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
497 the beginning of the resource.
498
499
500
501 .. _texture_barrier:
502
503 texture_barrier
504 %%%%%%%%%%%%%%%
505
506 This function flushes all pending writes to the currently-set surfaces and
507 invalidates all read caches of the currently-set samplers.
508
509
510
511 .. _pipe_transfer:
512
513 PIPE_TRANSFER
514 ^^^^^^^^^^^^^
515
516 These flags control the behavior of a transfer object.
517
518 ``PIPE_TRANSFER_READ``
519 Resource contents read back (or accessed directly) at transfer create time.
520
521 ``PIPE_TRANSFER_WRITE``
522 Resource contents will be written back at transfer_unmap time (or modified
523 as a result of being accessed directly).
524
525 ``PIPE_TRANSFER_MAP_DIRECTLY``
526 a transfer should directly map the resource. May return NULL if not supported.
527
528 ``PIPE_TRANSFER_DISCARD_RANGE``
529 The memory within the mapped region is discarded. Cannot be used with
530 ``PIPE_TRANSFER_READ``.
531
532 ``PIPE_TRANSFER_DISCARD_WHOLE_RESOURCE``
533 Discards all memory backing the resource. It should not be used with
534 ``PIPE_TRANSFER_READ``.
535
536 ``PIPE_TRANSFER_DONTBLOCK``
537 Fail if the resource cannot be mapped immediately.
538
539 ``PIPE_TRANSFER_UNSYNCHRONIZED``
540 Do not synchronize pending operations on the resource when mapping. The
541 interaction of any writes to the map and any operations pending on the
542 resource are undefined. Cannot be used with ``PIPE_TRANSFER_READ``.
543
544 ``PIPE_TRANSFER_FLUSH_EXPLICIT``
545 Written ranges will be notified later with :ref:`transfer_flush_region`.
546 Cannot be used with ``PIPE_TRANSFER_READ``.
547
548
549 Compute kernel execution
550 ^^^^^^^^^^^^^^^^^^^^^^^^
551
552 A compute program can be defined, bound or destroyed using
553 ``create_compute_state``, ``bind_compute_state`` or
554 ``destroy_compute_state`` respectively.
555
556 Any of the subroutines contained within the compute program can be
557 executed on the device using the ``launch_grid`` method. This method
558 will execute as many instances of the program as elements in the
559 specified N-dimensional grid, hopefully in parallel.
560
561 The compute program has access to four special resources:
562
563 * ``GLOBAL`` represents a memory space shared among all the threads
564 running on the device. An arbitrary buffer created with the
565 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the
566 ``set_global_binding`` method.
567
568 * ``LOCAL`` represents a memory space shared among all the threads
569 running in the same working group. The initial contents of this
570 resource are undefined.
571
572 * ``PRIVATE`` represents a memory space local to a single thread.
573 The initial contents of this resource are undefined.
574
575 * ``INPUT`` represents a read-only memory space that can be
576 initialized at ``launch_grid`` time.
577
578 These resources use a byte-based addressing scheme, and they can be
579 accessed from the compute program by means of the LOAD/STORE TGSI
580 opcodes. Additional resources to be accessed using the same opcodes
581 may be specified by the user with the ``set_compute_resources``
582 method.
583
584 In addition, normal texture sampling is allowed from the compute
585 program: ``bind_compute_sampler_states`` may be used to set up texture
586 samplers for the compute stage and ``set_compute_sampler_views`` may
587 be used to bind a number of sampler views to it.