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