Debian Codegraph @

docs/gallium/context.rst

raw
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, geometry and compute shaders with the ``bind_sampler_states``
29 function. The ``start`` and ``num_samplers`` parameters indicate a range
30 of samplers to change. NOTE: at this time, start is always zero and
31 the CSO module will always replace all samplers at once (no sub-ranges).
32 This may change in the future.
33 * :ref:`Rasterizer`: ``*_rasterizer_state``
34 * :ref:`depth-stencil-alpha`: ``*_depth_stencil_alpha_state``
35 * :ref:`Shader`: These are create, bind and destroy methods for vertex,
36 fragment and geometry shaders.
37 * :ref:`vertexelements`: ``*_vertex_elements_state``
38
39
40 Resource Binding State
41 ^^^^^^^^^^^^^^^^^^^^^^
42
43 This state describes how resources in various flavors (textures,
44 buffers, surfaces) are bound to the driver.
45
46
47 * ``set_constant_buffer`` sets a constant buffer to be used for a given shader
48 type. index is used to indicate which buffer to set (some APIs may allow
49 multiple ones to be set, and binding a specific one later, though drivers
50 are mostly restricted to the first one right now).
51 If take_ownership is true, the buffer reference is passed to the driver, so
52 that the driver doesn't have to increment the reference count.
53
54 * ``set_inlinable_constants`` sets inlinable constants for constant buffer 0.
55
56 These are constants that the driver would like to inline in the IR
57 of the current shader and recompile it. Drivers can determine which
58 constants they prefer to inline in finalize_nir and store that
59 information in shader_info::*inlinable_uniform*. When the state tracker
60 or frontend uploads constants to a constant buffer, it can pass
61 inlinable constants separately via this call.
62
63 Any ``set_constant_buffer`` call invalidates inlinable constants, so
64 ``set_inlinable_constants`` must be called after it. Binding a shader also
65 invalidates this state.
66
67 There is no ``PIPE_CAP`` for this. Drivers shouldn't set the shader_info
68 fields if they don't implement ``set_inlinable_constants``.
69
70 * ``set_framebuffer_state``
71
72 * ``set_vertex_buffers``
73
74
75 Non-CSO State
76 ^^^^^^^^^^^^^
77
78 These pieces of state are too small, variable, and/or trivial to have CSO
79 objects. They all follow simple, one-method binding calls, e.g.
80 ``set_blend_color``.
81
82 * ``set_stencil_ref`` sets the stencil front and back reference values
83 which are used as comparison values in stencil test.
84 * ``set_blend_color``
85 * ``set_sample_mask`` sets the per-context multisample sample mask. Note
86 that this takes effect even if multisampling is not explicitly enabled if
87 the framebuffer surface(s) are multisampled. Also, this mask is AND-ed
88 with the optional fragment shader sample mask output (when emitted).
89 * ``set_sample_locations`` sets the sample locations used for rasterization.
90 ```get_sample_position``` still returns the default locations. When NULL,
91 the default locations are used.
92 * ``set_min_samples`` sets the minimum number of samples that must be run.
93 * ``set_clip_state``
94 * ``set_polygon_stipple``
95 * ``set_scissor_states`` sets the bounds for the scissor test, which culls
96 pixels before blending to render targets. If the :ref:`Rasterizer` does
97 not have the scissor test enabled, then the scissor bounds never need to
98 be set since they will not be used. Note that scissor xmin and ymin are
99 inclusive, but xmax and ymax are exclusive. The inclusive ranges in x
100 and y would be [xmin..xmax-1] and [ymin..ymax-1]. The number of scissors
101 should be the same as the number of set viewports and can be up to
102 PIPE_MAX_VIEWPORTS.
103 * ``set_viewport_states``
104 * ``set_window_rectangles`` sets the window rectangles to be used for
105 rendering, as defined by :ext:`GL_EXT_window_rectangles`. There are two
106 modes - include and exclude, which define whether the supplied
107 rectangles are to be used for including fragments or excluding
108 them. All of the rectangles are ORed together, so in exclude mode,
109 any fragment inside any rectangle would be culled, while in include
110 mode, any fragment outside all rectangles would be culled. xmin/ymin
111 are inclusive, while xmax/ymax are exclusive (same as scissor states
112 above). Note that this only applies to draws, not clears or
113 blits. (Blits have their own way to pass the requisite rectangles
114 in.)
115 * ``set_tess_state`` configures the default tessellation parameters:
116
117 * ``default_outer_level`` is the default value for the outer tessellation
118 levels. This corresponds to GL's ``PATCH_DEFAULT_OUTER_LEVEL``.
119 * ``default_inner_level`` is the default value for the inner tessellation
120 levels. This corresponds to GL's ``PATCH_DEFAULT_INNER_LEVEL``.
121 * ``set_patch_vertices`` sets the number of vertices per input patch
122 for tessellation.
123
124 * ``set_debug_callback`` sets the callback to be used for reporting
125 various debug messages, eventually reported via :ext:`GL_KHR_debug` and
126 similar mechanisms.
127
128 Samplers
129 ^^^^^^^^
130
131 pipe_sampler_state objects control how textures are sampled (coordinate wrap
132 modes, interpolation modes, etc). Samplers are only required for texture
133 instructions for which nir_tex_instr_need_sampler returns true. Drivers must
134 ignore samplers for other texture instructions. Frontends may or may not bind
135 samplers when no texture instruction use them. Notably, frontends may not bind
136 samplers for texture buffer objects, which are never accessed with samplers.
137
138 Sampler Views
139 ^^^^^^^^^^^^^
140
141 These are the means to bind textures to shader stages. To create one, specify
142 its format, swizzle and LOD range in sampler view template.
143
144 If texture format is different than template format, it is said the texture
145 is being cast to another format. Casting can be done only between compatible
146 formats, that is formats that have matching component order and sizes.
147
148 Swizzle fields specify the way in which fetched texel components are placed
149 in the result register. For example, ``swizzle_r`` specifies what is going to be
150 placed in first component of result register.
151
152 The ``first_level`` and ``last_level`` fields of sampler view template specify
153 the LOD range the texture is going to be constrained to. Note that these
154 values are in addition to the respective min_lod, max_lod values in the
155 pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip
156 level used for sampling from the resource is effectively the fifth).
157
158 The ``first_layer`` and ``last_layer`` fields specify the layer range the
159 texture is going to be constrained to. Similar to the LOD range, this is added
160 to the array index which is used for sampling.
161
162 * ``set_sampler_views`` binds an array of sampler views to a shader stage.
163 Every binding point acquires a reference
164 to a respective sampler view and releases a reference to the previous
165 sampler view.
166
167 Sampler views outside of ``[start_slot, start_slot + num_views)`` are
168 unmodified. If ``views`` is NULL, the behavior is the same as if
169 ``views[n]`` was NULL for the entire range, i.e. releasing the reference
170 for all the sampler views in the specified range.
171
172 * ``create_sampler_view`` creates a new sampler view. ``texture`` is associated
173 with the sampler view which results in sampler view holding a reference
174 to the texture. Format specified in template must be compatible
175 with texture format.
176
177 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
178 to associated texture.
179
180 Hardware Atomic buffers
181 ^^^^^^^^^^^^^^^^^^^^^^^
182
183 Buffers containing HW atomics are required to support the feature
184 on some drivers.
185
186 Drivers that require this need to fill the ``set_hw_atomic_buffers`` method.
187
188 Shader Resources
189 ^^^^^^^^^^^^^^^^
190
191 Shader resources are textures or buffers that may be read or written
192 from a shader without an associated sampler. This means that they
193 have no support for floating point coordinates, address wrap modes or
194 filtering.
195
196 There are 2 types of shader resources: buffers and images.
197
198 Buffers are specified using the ``set_shader_buffers`` method.
199
200 Images are specified using the ``set_shader_images`` method. When binding
201 images, the ``level``, ``first_layer`` and ``last_layer`` pipe_image_view
202 fields specify the mipmap level and the range of layers the image will be
203 constrained to.
204
205 Surfaces
206 ^^^^^^^^
207
208 These are the means to use resources as color render targets or depthstencil
209 attachments. To create one, specify the mip level, the range of layers, and
210 the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET).
211 Note that layer values are in addition to what is indicated by the geometry
212 shader output variable XXX_FIXME (that is if first_layer is 3 and geometry
213 shader indicates index 2, the 5th layer of the resource will be used). These
214 first_layer and last_layer parameters will only be used for 1d array, 2d array,
215 cube, and 3d textures otherwise they are 0.
216
217 * ``create_surface`` creates a new surface.
218
219 * ``surface_destroy`` destroys a surface and releases its reference to the
220 associated resource.
221
222 Stream output targets
223 ^^^^^^^^^^^^^^^^^^^^^
224
225 Stream output, also known as transform feedback, allows writing the primitives
226 produced by the vertex pipeline to buffers. This is done after the geometry
227 shader or vertex shader if no geometry shader is present.
228
229 The stream output targets are views into buffer resources which can be bound
230 as stream outputs and specify a memory range where it's valid to write
231 primitives. The pipe driver must implement memory protection such that any
232 primitives written outside of the specified memory range are discarded.
233
234 Two stream output targets can use the same resource at the same time, but
235 with a disjoint memory range.
236
237 Additionally, the stream output target internally maintains the offset
238 into the buffer which is incremented every time something is written to it.
239 The internal offset is equal to how much data has already been written.
240 It can be stored in device memory and the CPU actually doesn't have to query
241 it.
242
243 The stream output target can be used in a draw command to provide
244 the vertex count. The vertex count is derived from the internal offset
245 discussed above.
246
247 * ``create_stream_output_target`` create a new target.
248
249 * ``stream_output_target_destroy`` destroys a target. Users of this should
250 use pipe_so_target_reference instead.
251
252 * ``set_stream_output_targets`` binds stream output targets. The parameter
253 offset is an array which specifies the internal offset of the buffer. The
254 internal offset is, besides writing, used for reading the data during the
255 draw_auto stage, i.e. it specifies how much data there is in the buffer
256 for the purposes of the draw_auto stage. -1 means the buffer should
257 be appended to, and everything else sets the internal offset.
258
259 * ``stream_output_target_offset`` Retrieve the internal stream offset from
260 an streamout target. This is used to implement Vulkan pause/resume support
261 which needs to pass the internal offset to the API.
262
263 NOTE: The currently-bound vertex or geometry shader must be compiled with
264 the properly-filled-in structure pipe_stream_output_info describing which
265 outputs should be written to buffers and how. The structure is part of
266 pipe_shader_state.
267
268 Clearing
269 ^^^^^^^^
270
271 Clear is one of the most difficult concepts to nail down to a single
272 interface (due to both different requirements from APIs and also driver/HW
273 specific differences).
274
275 ``clear`` initializes some or all of the surfaces currently bound to
276 the framebuffer to particular RGBA, depth, or stencil values.
277 Currently, this does not take into account color or stencil write masks (as
278 used by GL), and always clears the whole surfaces (no scissoring as used by
279 GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
280 only depth or stencil in a combined depth/stencil surface.
281 If a surface includes several layers then all layers will be cleared.
282
283 ``clear_render_target`` clears a single color rendertarget with the specified
284 color value. While it is only possible to clear one surface at a time (which can
285 include several layers), this surface need not be bound to the framebuffer.
286 If render_condition_enabled is false, any current rendering condition is ignored
287 and the clear will be unconditional.
288
289 ``clear_depth_stencil`` clears a single depth, stencil or depth/stencil surface
290 with the specified depth and stencil values (for combined depth/stencil buffers,
291 it is also possible to only clear one or the other part). While it is only
292 possible to clear one surface at a time (which can include several layers),
293 this surface need not be bound to the framebuffer.
294 If render_condition_enabled is false, any current rendering condition is ignored
295 and the clear will be unconditional.
296
297 ``clear_texture`` clears a non-PIPE_BUFFER resource's specified level
298 and bounding box with a clear value provided in that resource's native
299 format.
300
301 ``clear_buffer`` clears a PIPE_BUFFER resource with the specified clear value
302 (which may be multiple bytes in length). Logically this is a memset with a
303 multi-byte element value starting at offset bytes from resource start, going
304 for size bytes. It is guaranteed that size % clear_value_size == 0.
305
306 Evaluating Depth Buffers
307 ^^^^^^^^^^^^^^^^^^^^^^^^
308
309 ``evaluate_depth_buffer`` is a hint to decompress the current depth buffer
310 assuming the current sample locations to avoid problems that could arise when
311 using programmable sample locations.
312
313 If a depth buffer is rendered with different sample location state than
314 what is current at the time of reading the depth buffer, the values may differ
315 because depth buffer compression can depend the sample locations.
316
317
318 Uploading
319 ^^^^^^^^^
320
321 For simple single-use uploads, use ``pipe_context::stream_uploader`` or
322 ``pipe_context::const_uploader``. The latter should be used for uploading
323 constants, while the former should be used for uploading everything else.
324 PIPE_USAGE_STREAM is implied in both cases, so don't use the uploaders
325 for static allocations.
326
327 Usage:
328
329 Call u_upload_alloc or u_upload_data as many times as you want. After you are
330 done, call u_upload_unmap. If the driver doesn't support persistent mappings,
331 u_upload_unmap makes sure the previously mapped memory is unmapped.
332
333 Gotchas:
334 - Always fill the memory immediately after u_upload_alloc. Any following call
335 to u_upload_alloc and u_upload_data can unmap memory returned by previous
336 u_upload_alloc.
337 - Don't interleave calls using stream_uploader and const_uploader. If you use
338 one of them, do the upload, unmap, and only then can you use the other one.
339
340
341 Drawing
342 ^^^^^^^
343
344 ``draw_vbo`` draws a specified primitive. The primitive mode and other
345 properties are described by ``pipe_draw_info``.
346
347 The ``mode``, ``start``, and ``count`` fields of ``pipe_draw_info`` specify the
348 the mode of the primitive and the vertices to be fetched, in the range between
349 ``start`` to ``start``+``count``-1, inclusive.
350
351 Every instance with instanceID in the range between ``start_instance`` and
352 ``start_instance``+``instance_count``-1, inclusive, will be drawn.
353
354 If ``index_size`` != 0, all vertex indices will be looked up from the index
355 buffer.
356
357 In indexed draw, ``min_index`` and ``max_index`` respectively provide a lower
358 and upper bound of the indices contained in the index buffer inside the range
359 between ``start`` to ``start``+``count``-1. This allows the driver to
360 determine which subset of vertices will be referenced during the draw call
361 without having to scan the index buffer. Providing a over-estimation of the
362 the true bounds, for example, a ``min_index`` and ``max_index`` of 0 and
363 0xffffffff respectively, must give exactly the same rendering, albeit with less
364 performance due to unreferenced vertex buffers being unnecessarily DMA'ed or
365 processed. Providing a underestimation of the true bounds will result in
366 undefined behavior, but should not result in program or system failure.
367
368 In case of non-indexed draw, ``min_index`` should be set to
369 ``start`` and ``max_index`` should be set to ``start``+``count``-1.
370
371 ``index_bias`` is a value added to every vertex index after lookup and before
372 fetching vertex attributes.
373
374 When drawing indexed primitives, the primitive restart index can be
375 used to draw disjoint primitive strips. For example, several separate
376 line strips can be drawn by designating a special index value as the
377 restart index. The ``primitive_restart`` flag enables/disables this
378 feature. The ``restart_index`` field specifies the restart index value.
379
380 When primitive restart is in use, array indexes are compared to the
381 restart index before adding the index_bias offset.
382
383 If a given vertex element has ``instance_divisor`` set to 0, it is said
384 it contains per-vertex data and effective vertex attribute address needs
385 to be recalculated for every index.
386
387 attribAddr = ``stride`` * index + ``src_offset``
388
389 If a given vertex element has ``instance_divisor`` set to non-zero,
390 it is said it contains per-instance data and effective vertex attribute
391 address needs to recalculated for every ``instance_divisor``-th instance.
392
393 attribAddr = ``stride`` * instanceID / ``instance_divisor`` + ``src_offset``
394
395 In the above formulas, ``src_offset`` is taken from the given vertex element
396 and ``stride`` is taken from a vertex buffer associated with the given
397 vertex element.
398
399 The calculated attribAddr is used as an offset into the vertex buffer to
400 fetch the attribute data.
401
402 The value of ``instanceID`` can be read in a vertex shader through a system
403 value register declared with INSTANCEID semantic name.
404
405
406 Queries
407 ^^^^^^^
408
409 Queries gather some statistic from the 3D pipeline over one or more
410 draws. Queries may be nested, though not all gallium frontends exercise this.
411
412 Queries can be created with ``create_query`` and deleted with
413 ``destroy_query``. To start a query, use ``begin_query``, and when finished,
414 use ``end_query`` to end the query.
415
416 ``create_query`` takes a query type (``PIPE_QUERY_*``), as well as an index,
417 which is the vertex stream for ``PIPE_QUERY_PRIMITIVES_GENERATED`` and
418 ``PIPE_QUERY_PRIMITIVES_EMITTED``, and allocates a query structure.
419
420 ``begin_query`` will clear/reset previous query results.
421
422 ``get_query_result`` is used to retrieve the results of a query. If
423 the ``wait`` parameter is TRUE, then the ``get_query_result`` call
424 will block until the results of the query are ready (and TRUE will be
425 returned). Otherwise, if the ``wait`` parameter is FALSE, the call
426 will not block and the return value will be TRUE if the query has
427 completed or FALSE otherwise.
428
429 ``get_query_result_resource`` is used to store the result of a query into
430 a resource without synchronizing with the CPU. This write will optionally
431 wait for the query to complete, and will optionally write whether the value
432 is available instead of the value itself.
433
434 ``set_active_query_state`` Set whether all current non-driver queries except
435 TIME_ELAPSED are active or paused.
436
437 The interface currently includes the following types of queries:
438
439 ``PIPE_QUERY_OCCLUSION_COUNTER`` counts the number of fragments which
440 are written to the framebuffer without being culled by
441 :ref:`depth-stencil-alpha` testing or shader KILL instructions.
442 The result is an unsigned 64-bit integer.
443 This query can be used with ``render_condition``.
444
445 In cases where a boolean result of an occlusion query is enough,
446 ``PIPE_QUERY_OCCLUSION_PREDICATE`` should be used. It is just like
447 ``PIPE_QUERY_OCCLUSION_COUNTER`` except that the result is a boolean
448 value of FALSE for cases where COUNTER would result in 0 and TRUE
449 for all other cases.
450 This query can be used with ``render_condition``.
451
452 In cases where a conservative approximation of an occlusion query is enough,
453 ``PIPE_QUERY_OCCLUSION_PREDICATE_CONSERVATIVE`` should be used. It behaves
454 like ``PIPE_QUERY_OCCLUSION_PREDICATE``, except that it may return TRUE in
455 additional, implementation-dependent cases.
456 This query can be used with ``render_condition``.
457
458 ``PIPE_QUERY_TIME_ELAPSED`` returns the amount of time, in nanoseconds,
459 the context takes to perform operations.
460 The result is an unsigned 64-bit integer.
461
462 ``PIPE_QUERY_TIMESTAMP`` returns a device/driver internal timestamp,
463 scaled to nanoseconds, recorded after all commands issued prior to
464 ``end_query`` have been processed.
465 This query does not require a call to ``begin_query``.
466 The result is an unsigned 64-bit integer.
467
468 ``PIPE_QUERY_TIMESTAMP_RAW`` returns a device/driver timestamp, recorded
469 after all commands issued prior to ``end_query`` have been processed.
470 This query does not require a call to ``begin_query``.
471 The result is an unsigned 64-bit integer. ``pipe_screen::convert_timestamp()``
472 should be implemented, to covert the raw timestamp to nanoseconds, if
473 this query type is supported.
474 ``PIPE_QUERY_TIMESTAMP_DISJOINT`` can be used to check the
475 internal timer resolution and whether the timestamp counter has become
476 unreliable due to things like throttling etc. - only if this is FALSE
477 a timestamp query (within the timestamp_disjoint query) should be trusted.
478 The result is a 64-bit integer specifying the timer resolution in Hz,
479 followed by a boolean value indicating whether the timestamp counter
480 is discontinuous or disjoint.
481
482 ``PIPE_QUERY_PRIMITIVES_GENERATED`` returns a 64-bit integer indicating
483 the number of primitives processed by the pipeline (regardless of whether
484 stream output is active or not).
485
486 ``PIPE_QUERY_PRIMITIVES_EMITTED`` returns a 64-bit integer indicating
487 the number of primitives written to stream output buffers.
488
489 ``PIPE_QUERY_SO_STATISTICS`` returns 2 64-bit integers corresponding to
490 the result of
491 ``PIPE_QUERY_PRIMITIVES_EMITTED`` and
492 the number of primitives that would have been written to stream output buffers
493 if they had infinite space available (primitives_storage_needed), in this order.
494 XXX the 2nd value is equivalent to ``PIPE_QUERY_PRIMITIVES_GENERATED`` but it is
495 unclear if it should be increased if stream output is not active.
496
497 ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` returns a boolean value indicating
498 whether a selected stream output target has overflowed as a result of the
499 commands issued between ``begin_query`` and ``end_query``.
500 This query can be used with ``render_condition``. The output stream is
501 selected by the stream number passed to ``create_query``.
502
503 ``PIPE_QUERY_SO_OVERFLOW_ANY_PREDICATE`` returns a boolean value indicating
504 whether any stream output target has overflowed as a result of the commands
505 issued between ``begin_query`` and ``end_query``. This query can be used
506 with ``render_condition``, and its result is the logical OR of multiple
507 ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` queries, one for each stream output
508 target.
509
510 ``PIPE_QUERY_GPU_FINISHED`` returns a boolean value indicating whether
511 all commands issued before ``end_query`` have completed. However, this
512 does not imply serialization.
513 This query does not require a call to ``begin_query``.
514
515 ``PIPE_QUERY_PIPELINE_STATISTICS`` returns an array of the following
516 64-bit integers:
517 Number of vertices read from vertex buffers.
518 Number of primitives read from vertex buffers.
519 Number of vertex shader threads launched.
520 Number of geometry shader threads launched.
521 Number of primitives generated by geometry shaders.
522 Number of primitives forwarded to the rasterizer.
523 Number of primitives rasterized.
524 Number of fragment shader threads launched.
525 Number of tessellation control shader threads launched.
526 Number of tessellation evaluation shader threads launched.
527 If a shader type is not supported by the device/driver,
528 the corresponding values should be set to 0.
529
530 ``PIPE_QUERY_PIPELINE_STATISTICS_SINGLE`` returns a single counter from
531 the ``PIPE_QUERY_PIPELINE_STATISTICS`` group. The specific counter must
532 be selected when calling ``create_query`` by passing one of the
533 ``PIPE_STAT_QUERY`` enums as the query's ``index``.
534
535 Gallium does not guarantee the availability of any query types; one must
536 always check the capabilities of the :ref:`Screen` first.
537
538
539 Conditional Rendering
540 ^^^^^^^^^^^^^^^^^^^^^
541
542 A drawing command can be skipped depending on the outcome of a query
543 (typically an occlusion query, or streamout overflow predicate).
544 The ``render_condition`` function specifies the query which should be checked
545 prior to rendering anything. Functions always honoring render_condition include
546 (and are limited to) draw_vbo and clear.
547 The blit, clear_render_target and clear_depth_stencil functions (but
548 not resource_copy_region, which seems inconsistent) can also optionally honor
549 the current render condition.
550
551 If ``render_condition`` is called with ``query`` = NULL, conditional
552 rendering is disabled and drawing takes place normally.
553
554 If ``render_condition`` is called with a non-null ``query`` subsequent
555 drawing commands will be predicated on the outcome of the query.
556 Commands will be skipped if ``condition`` is equal to the predicate result
557 (for non-boolean queries such as OCCLUSION_QUERY, zero counts as FALSE,
558 non-zero as TRUE).
559
560 If ``mode`` is PIPE_RENDER_COND_WAIT the driver will wait for the
561 query to complete before deciding whether to render.
562
563 If ``mode`` is PIPE_RENDER_COND_NO_WAIT and the query has not yet
564 completed, the drawing command will be executed normally. If the query
565 has completed, drawing will be predicated on the outcome of the query.
566
567 If ``mode`` is PIPE_RENDER_COND_BY_REGION_WAIT or
568 PIPE_RENDER_COND_BY_REGION_NO_WAIT rendering will be predicated as above
569 for the non-REGION modes but in the case that an occlusion query returns
570 a non-zero result, regions which were occluded may be omitted by subsequent
571 drawing commands. This can result in better performance with some GPUs.
572 Normally, if the occlusion query returned a non-zero result subsequent
573 drawing happens normally so fragments may be generated, shaded and
574 processed even where they're known to be obscured.
575
576 The ''render_condition_mem'' function specifies the drawing is dependent
577 on a value in memory. A buffer resource and offset denote which 32-bit
578 value to use for the query. This is used for Vulkan API.
579
580 Flushing
581 ^^^^^^^^
582
583 ``flush``
584
585 PIPE_FLUSH_END_OF_FRAME: Whether the flush marks the end of frame.
586
587 PIPE_FLUSH_DEFERRED: It is not required to flush right away, but it is required
588 to return a valid fence. If fence_finish is called with the returned fence
589 and the context is still unflushed, and the ctx parameter of fence_finish is
590 equal to the context where the fence was created, fence_finish will flush
591 the context.
592
593 PIPE_FLUSH_ASYNC: The flush is allowed to be asynchronous. Unlike
594 ``PIPE_FLUSH_DEFERRED``, the driver must still ensure that the returned fence
595 will finish in finite time. However, subsequent operations in other contexts of
596 the same screen are no longer guaranteed to happen after the flush. Drivers
597 which use this flag must implement pipe_context::fence_server_sync.
598
599 PIPE_FLUSH_HINT_FINISH: Hints to the driver that the caller will immediately
600 wait for the returned fence.
601
602 Additional flags may be set together with ``PIPE_FLUSH_DEFERRED`` for even
603 finer-grained fences. Note that as a general rule, GPU caches may not have been
604 flushed yet when these fences are signaled. Drivers are free to ignore these
605 flags and create normal fences instead. At most one of the following flags can
606 be specified:
607
608 PIPE_FLUSH_TOP_OF_PIPE: The fence should be signaled as soon as the next
609 command is ready to start executing at the top of the pipeline, before any of
610 its data is actually read (including indirect draw parameters).
611
612 PIPE_FLUSH_BOTTOM_OF_PIPE: The fence should be signaled as soon as the previous
613 command has finished executing on the GPU entirely (but data written by the
614 command may still be in caches and inaccessible to the CPU).
615
616
617 ``flush_resource``
618
619 Flush the resource cache, so that the resource can be used
620 by an external client. Possible usage:
621 - flushing a resource before presenting it on the screen
622 - flushing a resource if some other process or device wants to use it
623 This shouldn't be used to flush caches if the resource is only managed
624 by a single pipe_screen and is not shared with another process.
625 (i.e. you shouldn't use it to flush caches explicitly if you want to e.g.
626 use the resource for texturing)
627
628 Fences
629 ^^^^^^
630
631 ``pipe_fence_handle``, and related methods, are used to synchronize
632 execution between multiple parties. Examples include CPU <-> GPU synchronization,
633 renderer <-> windowing system, multiple external APIs, etc.
634
635 A ``pipe_fence_handle`` can either be 'one time use' or 're-usable'. A 'one time use'
636 fence behaves like a traditional GPU fence. Once it reaches the signaled state it
637 is forever considered to be signaled.
638
639 Once a re-usable ``pipe_fence_handle`` becomes signaled, it can be reset
640 back into an unsignaled state. The ``pipe_fence_handle`` will be reset to
641 the unsignaled state by performing a wait operation on said object, i.e.
642 ``fence_server_sync``. As a corollary to this behavior, a re-usable
643 ``pipe_fence_handle`` can only have one waiter.
644
645 This behavior is useful in producer <-> consumer chains. It helps avoid
646 unnecessarily sharing a new ``pipe_fence_handle`` each time a new frame is
647 ready. Instead, the fences are exchanged once ahead of time, and access is synchronized
648 through GPU signaling instead of direct producer <-> consumer communication.
649
650 ``fence_server_sync`` inserts a wait command into the GPU's command stream.
651
652 ``fence_server_signal`` inserts a signal command into the GPU's command stream.
653
654 There are no guarantees that the wait/signal commands will be flushed when
655 calling ``fence_server_sync`` or ``fence_server_signal``. An explicit
656 call to ``flush`` is required to make sure the commands are emitted to the GPU.
657
658 The Gallium implementation may implicitly ``flush`` the command stream during a
659 ``fence_server_sync`` or ``fence_server_signal`` call if necessary.
660
661 Gallium frontends must ensure that ``fence_server_signal`` returns before calling
662 ``fence_server_sync`` on the same ``pipe_fence_handle`` even if those calls are made on
663 a different ``pipe_context``.
664
665 Resource Busy Queries
666 ^^^^^^^^^^^^^^^^^^^^^
667
668 ``is_resource_referenced``
669
670
671
672 Blitting
673 ^^^^^^^^
674
675 These methods emulate classic blitter controls.
676
677 These methods operate directly on ``pipe_resource`` objects, and stand
678 apart from any 3D state in the context. Each method is assumed to have an
679 implicit memory barrier around itself. They do not need any explicit
680 ``memory_barrier``. Blitting functionality may be moved to a separate
681 abstraction at some point in the future.
682
683 ``resource_copy_region`` blits a region of a resource to a region of another
684 resource, provided that both resources have the same format, or compatible
685 formats, i.e., formats for which copying the bytes from the source resource
686 unmodified to the destination resource will achieve the same effect of a
687 textured quad blitter.. The source and destination may be the same resource,
688 but overlapping blits are not permitted.
689 This can be considered the equivalent of a CPU memcpy.
690
691 ``blit`` blits a region of a resource to a region of another resource, including
692 scaling, format conversion, and up-/downsampling, as well as a destination clip
693 rectangle (scissors) and window rectangles. It can also optionally honor the
694 current render condition (but either way the blit itself never contributes
695 anything to queries currently gathering data).
696 As opposed to manually drawing a textured quad, this lets the pipe driver choose
697 the optimal method for blitting (like using a special 2D engine), and usually
698 offers, for example, accelerated stencil-only copies even where
699 pipe_caps.shader_stencil_export is not available.
700
701
702 Transfers
703 ^^^^^^^^^
704
705 These methods are used to get data to/from a resource.
706
707 ``transfer_map`` creates a memory mapping and the transfer object
708 associated with it.
709 The returned pointer points to the start of the mapped range according to
710 the box region, not the beginning of the resource. If transfer_map fails,
711 the returned pointer to the buffer memory is NULL, and the pointer
712 to the transfer object remains unchanged (i.e. it can be non-NULL).
713
714 When mapping an MSAA surface, the samples are implicitly resolved to
715 single-sampled for reads (returning the first sample for depth/stencil/integer,
716 averaged for others). See u_transfer_helper's U_TRANSFER_HELPER_MSAA_MAP for a
717 way to get that behavior using a resolve blit.
718
719 ``transfer_unmap`` remove the memory mapping for and destroy
720 the transfer object. The pointer into the resource should be considered
721 invalid and discarded.
722
723 ``texture_subdata`` and ``buffer_subdata`` perform a simplified
724 transfer for simple writes. Basically transfer_map, data write, and
725 transfer_unmap all in one.
726
727
728 The box parameter to some of these functions defines a 1D, 2D or 3D
729 region of pixels. This is self-explanatory for 1D, 2D and 3D texture
730 targets.
731
732 For PIPE_TEXTURE_1D_ARRAY and PIPE_TEXTURE_2D_ARRAY, the box::z and box::depth
733 fields refer to the array dimension of the texture.
734
735 For PIPE_TEXTURE_CUBE, the box:z and box::depth fields refer to the
736 faces of the cube map (z + depth <= 6).
737
738 For PIPE_TEXTURE_CUBE_ARRAY, the box:z and box::depth fields refer to both
739 the face and array dimension of the texture (face = z % 6, array = z / 6).
740
741
742 .. _transfer_flush_region:
743
744 transfer_flush_region
745 %%%%%%%%%%%%%%%%%%%%%
746
747 If a transfer was created with ``FLUSH_EXPLICIT``, it will not automatically
748 be flushed on write or unmap. Flushes must be requested with
749 ``transfer_flush_region``. Flush ranges are relative to the mapped range, not
750 the beginning of the resource.
751
752
753
754 .. _texture_barrier:
755
756 texture_barrier
757 %%%%%%%%%%%%%%%
758
759 This function flushes all pending writes to the currently-set surfaces and
760 invalidates all read caches of the currently-set samplers. This can be used
761 for both regular textures as well as for framebuffers read via FBFETCH.
762
763
764
765 .. _memory_barrier:
766
767 memory_barrier
768 %%%%%%%%%%%%%%%
769
770 This function flushes caches according to which of the PIPE_BARRIER_* flags
771 are set.
772
773
774
775 .. _resource_commit:
776
777 resource_commit
778 %%%%%%%%%%%%%%%
779
780 This function changes the commit state of a part of a sparse resource. Sparse
781 resources are created by setting the ``PIPE_RESOURCE_FLAG_SPARSE`` flag when
782 calling ``resource_create``. Initially, sparse resources only reserve a virtual
783 memory region that is not backed by memory (i.e., it is uncommitted). The
784 ``resource_commit`` function can be called to commit or uncommit parts (or all)
785 of a resource. The driver manages the underlying backing memory.
786
787 The contents of newly committed memory regions are undefined. Calling this
788 function to commit an already committed memory region is allowed and leaves its
789 content unchanged. Similarly, calling this function to uncommit an already
790 uncommitted memory region is allowed.
791
792 For buffers, the given box must be aligned to multiples of
793 ``pipe_caps.sparse_buffer_page_size``. As an exception to this rule, if the size
794 of the buffer is not a multiple of the page size, changing the commit state of
795 the last (partial) page requires a box that ends at the end of the buffer
796 (i.e., box->x + box->width == buffer->width0).
797
798
799
800 .. _pipe_transfer:
801
802 PIPE_MAP
803 ^^^^^^^^^^^^^
804
805 These flags control the behavior of a transfer object.
806
807 ``PIPE_MAP_READ``
808 Resource contents read back (or accessed directly) at transfer create time.
809
810 ``PIPE_MAP_WRITE``
811 Resource contents will be written back at transfer_unmap time (or modified
812 as a result of being accessed directly).
813
814 ``PIPE_MAP_DIRECTLY``
815 a transfer should directly map the resource. May return NULL if not supported.
816
817 ``PIPE_MAP_DISCARD_RANGE``
818 The memory within the mapped region is discarded. Cannot be used with
819 ``PIPE_MAP_READ``.
820
821 ``PIPE_MAP_DISCARD_WHOLE_RESOURCE``
822 Discards all memory backing the resource. It should not be used with
823 ``PIPE_MAP_READ``.
824
825 ``PIPE_MAP_DONTBLOCK``
826 Fail if the resource cannot be mapped immediately.
827
828 ``PIPE_MAP_UNSYNCHRONIZED``
829 Do not synchronize pending operations on the resource when mapping. The
830 interaction of any writes to the map and any operations pending on the
831 resource are undefined. Cannot be used with ``PIPE_MAP_READ``.
832
833 ``PIPE_MAP_FLUSH_EXPLICIT``
834 Written ranges will be notified later with :ref:`transfer_flush_region`.
835 Cannot be used with ``PIPE_MAP_READ``.
836
837 ``PIPE_MAP_PERSISTENT``
838 Allows the resource to be used for rendering while mapped.
839 PIPE_RESOURCE_FLAG_MAP_PERSISTENT must be set when creating
840 the resource.
841 If COHERENT is not set, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER)
842 must be called to ensure the device can see what the CPU has written.
843
844 ``PIPE_MAP_COHERENT``
845 If PERSISTENT is set, this ensures any writes done by the device are
846 immediately visible to the CPU and vice versa.
847 PIPE_RESOURCE_FLAG_MAP_COHERENT must be set when creating
848 the resource.
849
850 Compute kernel execution
851 ^^^^^^^^^^^^^^^^^^^^^^^^
852
853 A compute program can be defined, bound or destroyed using
854 ``create_compute_state``, ``bind_compute_state`` or
855 ``destroy_compute_state`` respectively.
856
857 Any of the subroutines contained within the compute program can be
858 executed on the device using the ``launch_grid`` method. This method
859 will execute as many instances of the program as elements in the
860 specified N-dimensional grid, hopefully in parallel.
861
862 The compute program has access to four special resources:
863
864 * ``GLOBAL`` represents a memory space shared among all the threads
865 running on the device. An arbitrary buffer created with the
866 ``PIPE_BIND_GLOBAL`` flag can be mapped into it using the
867 ``set_global_binding`` method.
868
869 * ``LOCAL`` represents a memory space shared among all the threads
870 running in the same working group. The initial contents of this
871 resource are undefined.
872
873 * ``PRIVATE`` represents a memory space local to a single thread.
874 The initial contents of this resource are undefined.
875
876 * ``INPUT`` represents a read-only memory space that can be
877 initialized at ``launch_grid`` time.
878
879 These resources use a byte-based addressing scheme, and they can be
880 accessed from the compute program by means of the LOAD/STORE TGSI
881 opcodes.
882
883 In addition, normal texture sampling is allowed from the compute
884 program: ``bind_sampler_states`` may be used to set up texture
885 samplers for the compute stage and ``set_sampler_views`` may
886 be used to bind a number of sampler views to it.
887
888 Compute kernel queries
889 ^^^^^^^^^^^^^^^^^^^^^^
890
891 .. _get_compute_state_info:
892
893 get_compute_state_info
894 %%%%%%%%%%%%%%%%%%%%%%
895
896 This function allows frontends to query kernel information defined inside
897 ``pipe_compute_state_object_info``.
898
899 .. _get_compute_state_subgroup_size:
900
901 get_compute_state_subgroup_size
902 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
903
904 This function returns the choosen subgroup size when ``launch_grid`` is
905 called with the given block size. This doesn't need to be implemented when
906 only one size is reported through ``pipe_compute_caps.subgroup_sizes`` or
907 ``pipe_compute_state_object_info::simd_sizes``.
908
909 Mipmap generation
910 ^^^^^^^^^^^^^^^^^
911
912 If pipe_caps.generate_mipmap is true, ``generate_mipmap`` can be used
913 to generate mipmaps for the specified texture resource.
914 It replaces texel image levels base_level+1 through
915 last_level for layers range from first_layer through last_layer.
916 It returns TRUE if mipmap generation succeeds, otherwise it
917 returns FALSE. Mipmap generation may fail when it is not supported
918 for particular texture types or formats.
919
920 Device resets
921 ^^^^^^^^^^^^^
922
923 Gallium frontends can query or request notifications of when the GPU
924 is reset for whatever reason (application error, driver error). When
925 a GPU reset happens, the context becomes unusable and all related state
926 should be considered lost and undefined. Despite that, context
927 notifications are single-shot, i.e. subsequent calls to
928 ``get_device_reset_status`` will return PIPE_NO_RESET.
929
930 * ``get_device_reset_status`` queries whether a device reset has happened
931 since the last call or since the last notification by callback.
932 * ``set_device_reset_callback`` sets a callback which will be called when
933 a device reset is detected. The callback is only called synchronously.
934
935 Bindless
936 ^^^^^^^^
937
938 If pipe_caps.bindless_texture is TRUE, the following ``pipe_context`` functions
939 are used to create/delete bindless handles, and to make them resident in the
940 current context when they are going to be used by shaders.
941
942 * ``create_texture_handle`` creates a 64-bit unsigned integer texture handle
943 that is going to be directly used in shaders.
944 * ``delete_texture_handle`` deletes a 64-bit unsigned integer texture handle.
945 * ``make_texture_handle_resident`` makes a 64-bit unsigned texture handle
946 resident in the current context to be accessible by shaders for texture
947 mapping.
948 * ``create_image_handle`` creates a 64-bit unsigned integer image handle that
949 is going to be directly used in shaders.
950 * ``delete_image_handle`` deletes a 64-bit unsigned integer image handle.
951 * ``make_image_handle_resident`` makes a 64-bit unsigned integer image handle
952 resident in the current context to be accessible by shaders for image loads,
953 stores and atomic operations.
954
955 Using several contexts
956 ----------------------
957
958 Several contexts from the same screen can be used at the same time. Objects
959 created on one context cannot be used in another context, but the objects
960 created by the screen methods can be used by all contexts.
961
962 Transfers
963 ^^^^^^^^^
964 A transfer on one context is not expected to synchronize properly with
965 rendering on other contexts, thus only areas not yet used for rendering should
966 be locked.
967
968 A flush is required after transfer_unmap to expect other contexts to see the
969 uploaded data, unless:
970
971 * Using persistent mapping. Associated with coherent mapping, unmapping the
972 resource is also not required to use it in other contexts. Without coherent
973 mapping, memory_barrier(PIPE_BARRIER_MAPPED_BUFFER) should be called on the
974 context that has mapped the resource. No flush is required.
975
976 * Mapping the resource with PIPE_MAP_DIRECTLY.