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