Debian Codegraph @

docs/gallium/screen.rst

raw
1 .. _screen:
2
3 Screen
4 ======
5
6 A screen is an object representing the context-independent part of a device.
7
8 Flags and enumerations
9 ----------------------
10
11 XXX some of these don't belong in this section.
12
13
14 .. _pipe_caps:
15
16 pipe_caps
17 ^^^^^^^^^^
18
19 Capability about the features and limits of the driver/GPU.
20
21 * ``pipe_caps.graphics``: Whether graphics is supported. If not, contexts can
22 only be created with PIPE_CONTEXT_COMPUTE_ONLY.
23 * ``pipe_caps.npot_textures``: Whether :term:`NPOT` textures may have repeat modes,
24 normalized coordinates, and mipmaps.
25 * ``pipe_caps.max_dual_source_render_targets``: How many dual-source blend RTs are support.
26 :ref:`Blend` for more information.
27 * ``pipe_caps.anisotropic_filter``: Whether textures can be filtered anisotropically.
28 * ``pipe_caps.max_render_targets``: The maximum number of render targets that may be
29 bound.
30 * ``pipe_caps.occlusion_query``: Whether occlusion queries are available.
31 * ``pipe_caps.query_time_elapsed``: Whether PIPE_QUERY_TIME_ELAPSED queries are available.
32 * ``pipe_caps.texture_shadow_map``: indicates whether the fragment shader hardware
33 can do the depth texture / Z comparison operation in TEX instructions
34 for shadow testing.
35 * ``pipe_caps.texture_swizzle``: Whether swizzling through sampler views is
36 supported.
37 * ``pipe_caps.max_texture_2d_size``: The maximum size of 2D (and 1D) textures.
38 * ``pipe_caps.max_texture_3d_levels``: The maximum number of mipmap levels available
39 for a 3D texture.
40 * ``pipe_caps.max_texture_cube_levels``: The maximum number of mipmap levels available
41 for a cubemap.
42 * ``pipe_caps.texture_mirror_clamp_to_edge``: Whether mirrored texture coordinates are
43 supported with the clamp-to-edge wrap mode.
44 * ``pipe_caps.texture_mirror_clamp``: Whether mirrored texture coordinates are supported
45 with clamp or clamp-to-border wrap modes.
46 * ``pipe_caps.blend_equation_separate``: Whether alpha blend equations may be different
47 from color blend equations, in :ref:`Blend` state.
48 * ``pipe_caps.max_stream_output_buffers``: The maximum number of stream buffers.
49 * ``pipe_caps.primitive_restart``: Whether primitive restart is supported.
50 * ``pipe_caps.primitive_restart_fixed_index``: Subset of
51 PRIMITIVE_RESTART where the restart index is always the fixed maximum
52 value for the index type.
53 * ``pipe_caps.indep_blend_enable``: Whether per-rendertarget blend enabling and channel
54 masks are supported. If 0, then the first rendertarget's blend mask is
55 replicated across all MRTs.
56 * ``pipe_caps.indep_blend_func``: Whether per-rendertarget blend functions are
57 available. If 0, then the first rendertarget's blend functions affect all
58 MRTs.
59 * ``pipe_caps.max_texture_array_layers``: The maximum number of texture array
60 layers supported. If 0, the array textures are not supported at all and
61 the ARRAY texture targets are invalid.
62 * ``pipe_caps.fs_coord_origin_upper_left``: Whether the upper-left origin
63 fragment convention is supported.
64 * ``pipe_caps.fs_coord_origin_lower_left``: Whether the lower-left origin
65 fragment convention is supported.
66 * ``pipe_caps.fs_coord_pixel_center_half_integer``: Whether the half-integer
67 pixel-center fragment convention is supported.
68 * ``pipe_caps.fs_coord_pixel_center_integer``: Whether the integer
69 pixel-center fragment convention is supported.
70 * ``pipe_caps.depth_clip_disable``: Whether the driver is capable of disabling
71 depth clipping (through pipe_rasterizer_state).
72 * ``pipe_caps.depth_clip_disable_separate``: Whether the driver is capable of
73 disabling depth clipping (through pipe_rasterizer_state) separately for
74 the near and far plane. If not, depth_clip_near and depth_clip_far will be
75 equal.
76 ``pipe_caps.depth_clamp_enable``: Whether the driver is capable of
77 enabling depth clamping (through pipe_rasterizer_state) separately from depth
78 clipping. If not, depth_clamp will be the inverse of depth_clip_far.
79 * ``pipe_caps.shader_stencil_export``: Whether a stencil reference value can be
80 written from a fragment shader.
81 * ``pipe_caps.vs_instanceid``: Whether ``SYSTEM_VALUE_INSTANCE_ID`` is
82 supported in the vertex shader.
83 * ``pipe_caps.vertex_element_instance_divisor``: Whether the driver supports
84 per-instance vertex attribs.
85 * ``pipe_caps.fragment_color_clamped``: Whether fragment color clamping is
86 supported. That is, is the pipe_rasterizer_state::clamp_fragment_color
87 flag supported by the driver? If not, gallium frontends will insert
88 clamping code into the fragment shaders when needed.
89
90 * ``pipe_caps.mixed_colorbuffer_formats``: Whether mixed colorbuffer formats are
91 supported, e.g. RGBA8 and RGBA32F as the first and second colorbuffer, resp.
92 * ``pipe_caps.vertex_color_unclamped``: Whether the driver is capable of
93 outputting unclamped vertex colors from a vertex shader. If unsupported,
94 the vertex colors are always clamped. This is the default for DX9 hardware.
95 * ``pipe_caps.vertex_color_clamped``: Whether the driver is capable of
96 clamping vertex colors when they come out of a vertex shader, as specified
97 by the pipe_rasterizer_state::clamp_vertex_color flag. If unsupported,
98 the vertex colors are never clamped. This is the default for DX10 hardware.
99 If both clamped and unclamped CAPs are supported, the clamping can be
100 controlled through pipe_rasterizer_state. If the driver cannot do vertex
101 color clamping, gallium frontends may insert clamping code into the vertex
102 shader.
103 * ``pipe_caps.glsl_feature_level``: Whether the driver supports features
104 equivalent to a specific GLSL version. E.g. for GLSL 1.3, report 130.
105 * ``pipe_caps.glsl_feature_level_compatibility``: Whether the driver supports
106 features equivalent to a specific GLSL version including all legacy OpenGL
107 features only present in the OpenGL compatibility profile.
108 The only legacy features that Gallium drivers must implement are
109 the legacy shader inputs and outputs (colors, texcoords, fog, clipvertex,
110 edge flag).
111 * ``pipe_caps.essl_feature_level``: An optional cap to allow drivers to
112 report a higher GLSL version for GLES contexts. This is useful when a
113 driver does not support all the required features for a higher GL version,
114 but does support the required features for a higher GLES version. A driver
115 is allowed to return ``0`` in which case ``pipe_caps.glsl_feature_level`` is
116 used.
117 Note that simply returning the same value as the GLSL feature level cap is
118 incorrect. For example, GLSL version 3.30 does not require
119 :ext:`GL_EXT_gpu_shader5`, but ESSL version 3.20 es does require
120 :ext:`GL_EXT_gpu_shader5`
121 * ``pipe_caps.quads_follow_provoking_vertex_convention``: Whether quads adhere to
122 the flatshade_first setting in ``pipe_rasterizer_state``.
123 * ``pipe_caps.user_vertex_buffers``: Whether the driver supports user vertex
124 buffers. If not, gallium frontends must upload all data which is not in HW
125 resources. If user-space buffers are supported, the driver must also still
126 accept HW resource buffers.
127 * ``pipe_caps.vertex_input_alignment``: This CAP describes a HW
128 limitation.
129 If ``PIPE_VERTEX_INPUT_ALIGNMENT_4BYTE```,
130 pipe_vertex_buffer::buffer_offset must always be aligned
131 to 4, and pipe_vertex_buffer::stride must always be aligned to 4,
132 and pipe_vertex_element::src_offset must always be
133 aligned to 4.
134 If ``PIPE_VERTEX_INPUT_ALIGNMENT_ELEMENT``,
135 the sum of
136 ``pipe_vertex_element::src_offset + pipe_vertex_buffer::buffer_offset + pipe_vertex_buffer::stride``
137 must always be aligned to the component size for the vertex attributes
138 which access that buffer.
139 If ``PIPE_VERTEX_INPUT_ALIGNMENT_NONE``, there are no restrictions on these values.
140 * ``pipe_caps.compute``: Whether the implementation supports the
141 compute entry points defined in pipe_context and pipe_screen.
142 * ``pipe_caps.constant_buffer_offset_alignment``: Describes the required
143 alignment of pipe_constant_buffer::buffer_offset.
144 * ``pipe_caps.start_instance``: Whether the driver supports
145 pipe_draw_info::start_instance.
146 * ``pipe_caps.query_timestamp``: Whether PIPE_QUERY_TIMESTAMP and
147 the pipe_screen::get_timestamp hook are implemented.
148 * ``pipe_caps.query_timestamp_bits``: How many bits the driver uses for the
149 results of GL_TIMESTAMP queries.
150 * ``pipe_caps.timer_resolution``: The resolution of the timer in nanos.
151 * ``pipe_caps.texture_multisample``: Whether all MSAA resources supported
152 for rendering are also supported for texturing.
153 * ``pipe_caps.min_map_buffer_alignment``: The minimum alignment that should be
154 expected for a pointer returned by transfer_map if the resource is
155 PIPE_BUFFER. In other words, the pointer returned by transfer_map is
156 always aligned to this value.
157 * ``pipe_caps.texture_buffer_offset_alignment``: Describes the required
158 alignment for pipe_sampler_view::u.buf.offset, in bytes.
159 If a driver does not support offset/size, it should return 0.
160 * ``pipe_caps.linear_image_pitch_alignment``: Describes the row pitch alignment
161 size that pipe_sampler_view::u.tex2d_from_buf must be multiple of, in pixels.
162 If a driver does not support images created from buffers, it should return 0.
163 * ``pipe_caps.linear_image_base_address_alignment``: Describes the minimum alignment
164 in pixels of the offset of a host pointer for images created from buffers.
165 If a driver does not support images created from buffers, it should return 0.
166 * ``pipe_caps.buffer_sampler_view_rgba_only``: Whether the driver only
167 supports R, RG, RGB and RGBA formats for PIPE_BUFFER sampler views.
168 When this is the case it should be assumed that the swizzle parameters
169 in the sampler view have no effect.
170 * ``pipe_caps.tgsi_texcoord``: This CAP describes a HW limitation.
171 If true, the hardware cannot replace arbitrary shader inputs with sprite
172 coordinates and hence the inputs that are desired to be replaceable must
173 be declared with TGSI_SEMANTIC_TEXCOORD instead of TGSI_SEMANTIC_GENERIC.
174 The rasterizer's sprite_coord_enable state therefore also applies to the
175 TEXCOORD semantic.
176 Also, TGSI_SEMANTIC_PCOORD becomes available, which labels a fragment shader
177 input that will always be replaced with sprite coordinates.
178 * ``pipe_caps.texture_transfer_modes``: The ``pipe_texture_transfer_mode`` modes
179 that are supported for implementing a texture transfer which needs format conversions
180 and swizzling in gallium frontends. Generally, all hardware drivers with
181 dedicated memory should return PIPE_TEXTURE_TRANSFER_BLIT and all software rasterizers
182 should return PIPE_TEXTURE_TRANSFER_DEFAULT. PIPE_TEXTURE_TRANSFER_COMPUTE requires drivers
183 to support 8bit and 16bit shader storage buffer writes and to implement
184 pipe_screen::is_compute_copy_faster.
185 * ``pipe_caps.query_pipeline_statistics``: Whether PIPE_QUERY_PIPELINE_STATISTICS
186 is supported.
187 * ``pipe_caps.texture_border_color_quirk``: Bitmask indicating whether special
188 considerations have to be given to the interaction between the border color
189 in the sampler object and the sampler view used with it.
190 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_R600 is set, the border color
191 may be affected in undefined ways for any kind of permutational swizzle
192 (any swizzle XYZW where X/Y/Z/W are not ZERO, ONE, or R/G/B/A respectively)
193 in the sampler view.
194 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_NV50 is set, the border color
195 state should be swizzled manually according to the swizzle in the sampler
196 view it is intended to be used with, or herein undefined results may occur
197 for permutational swizzles.
198 * ``pipe_caps.max_texel_buffer_elements``: The maximum accessible number of
199 elements within a sampler buffer view and image buffer view. This is unsigned
200 integer with the maximum of 4G - 1.
201 * ``pipe_caps.max_viewports``: The maximum number of viewports (and scissors
202 since they are linked) a driver can support. Returning 0 is equivalent
203 to returning 1 because every driver has to support at least a single
204 viewport/scissor combination.
205 * ``pipe_caps.endianness``:: The endianness of the device. Either
206 PIPE_ENDIAN_BIG or PIPE_ENDIAN_LITTLE.
207 * ``pipe_caps.mixed_framebuffer_sizes``: Whether it is allowed to have
208 different sizes for fb color/zs attachments. This controls whether
209 :ext:`GL_ARB_framebuffer_object` is provided.
210 * ``pipe_caps.vs_layer_viewport``: Whether ``VARYING_SLOT_LAYER`` and
211 ``VARYING_SLOT_VIEWPORT`` are supported as vertex shader outputs. Note that
212 the viewport will only be used if multiple viewports are exposed.
213 * ``pipe_caps.max_geometry_output_vertices``: The maximum number of vertices
214 output by a single invocation of a geometry shader.
215 * ``pipe_caps.max_geometry_total_output_components``: The maximum number of
216 vertex components output by a single invocation of a geometry shader.
217 This is the product of the number of attribute components per vertex and
218 the number of output vertices.
219 * ``pipe_caps.max_texture_gather_components``: Max number of components
220 in format that texture gather can operate on. 1 == RED, ALPHA etc,
221 4 == All formats.
222 * ``pipe_caps.texture_gather_sm5``: Whether the texture gather
223 hardware implements the SM5 features, component selection,
224 shadow comparison, and run-time offsets.
225 * ``pipe_caps.buffer_map_persistent_coherent``: Whether
226 PIPE_MAP_PERSISTENT and PIPE_MAP_COHERENT are supported
227 for buffers.
228 * ``pipe_caps.texture_query_lod``: Whether the ``LODQ`` instruction is
229 supported.
230 * ``pipe_caps.min_texture_gather_offset``: The minimum offset that can be used
231 in conjunction with a texture gather opcode.
232 * ``pipe_caps.max_texture_gather_offset``: The maximum offset that can be used
233 in conjunction with a texture gather opcode.
234 * ``pipe_caps.sample_shading``: Whether there is support for per-sample
235 shading. The context->set_min_samples function will be expected to be
236 implemented.
237 * ``pipe_caps.texture_gather_offsets``: Whether the ``TG4`` instruction can
238 accept 4 offsets.
239 * ``pipe_caps.vs_window_space_position``: Whether window-space position is
240 supported, which disables clipping and viewport transformation.
241 * ``pipe_caps.max_vertex_streams``: The maximum number of vertex streams
242 supported by the geometry shader. If stream-out is supported, this should be
243 at least 1. If stream-out is not supported, this should be 0.
244 * ``pipe_caps.draw_indirect``: Whether the driver supports taking draw arguments
245 { count, instance_count, start, index_bias } from a PIPE_BUFFER resource.
246 See pipe_draw_info.
247 * ``pipe_caps.multi_draw_indirect``: Whether the driver supports
248 pipe_draw_info::indirect_stride and ::indirect_count
249 * ``pipe_caps.multi_draw_indirect_params``: Whether the driver supports
250 taking the number of indirect draws from a separate parameter
251 buffer, see pipe_draw_indirect_info::indirect_draw_count.
252 * ``pipe_caps.multi_draw_indirect_partial_stride``: Whether the driver supports
253 indirect draws with an arbitrary stride.
254 * ``pipe_caps.fs_fine_derivative``: Whether the fragment shader supports
255 the FINE versions of DDX/DDY.
256 * ``pipe_caps.vendor_id``: The vendor ID of the underlying hardware. If it's
257 not available one should return 0xFFFFFFFF.
258 * ``pipe_caps.device_id``: The device ID (PCI ID) of the underlying hardware.
259 0xFFFFFFFF if not available.
260 * ``pipe_caps.accelerated``: Whether the renderer is hardware accelerated. 0 means
261 not accelerated (i.e. CPU rendering), 1 means accelerated (i.e. GPU rendering),
262 -1 means unknown (i.e. an API translation driver which doesn't known what kind of
263 hardware it's running above).
264 * ``pipe_caps.video_memory``: The amount of video memory in megabytes.
265 * ``pipe_caps.uma``: If the device has a unified memory architecture or on-card
266 memory and GART.
267 * ``pipe_caps.conditional_render_inverted``: Whether the driver supports inverted
268 condition for conditional rendering.
269 * ``pipe_caps.max_vertex_attrib_stride``: The maximum supported vertex stride.
270 * ``pipe_caps.sampler_view_target``: Whether the sampler view's target can be
271 different than the underlying resource's, as permitted by
272 :ext:`GL_ARB_texture_view`. For example a 2d array texture may be reinterpreted as a
273 cube (array) texture and vice-versa.
274 * ``pipe_caps.clip_halfz``: Whether the driver supports the
275 pipe_rasterizer_state::clip_halfz being set to true. This is required
276 for enabling :ext:`GL_ARB_clip_control`.
277 * ``pipe_caps.polygon_offset_clamp``: If true, the driver implements support
278 for ``pipe_rasterizer_state::offset_clamp``.
279 * ``pipe_caps.multisample_z_resolve``: Whether the driver supports blitting
280 a multisampled depth buffer into a single-sampled texture (or depth buffer).
281 Only the first sampled should be copied.
282 * ``pipe_caps.resource_from_user_memory``: Whether the driver can create
283 a pipe_resource where an already-existing piece of (malloc'd) user memory
284 is used as its backing storage. In other words, whether the driver can map
285 existing user memory into the device address space for direct device access.
286 The create function is pipe_screen::resource_from_user_memory. The address
287 and size must be page-aligned.
288 * ``pipe_caps.resource_from_user_memory_compute_only``: Same as
289 ``pipe_caps.resource_from_user_memory`` but indicates it is only supported from
290 the compute engines.
291 * ``pipe_caps.device_reset_status_query``:
292 Whether pipe_context::get_device_reset_status is implemented.
293 * ``pipe_caps.max_shader_patch_varyings``:
294 How many per-patch outputs and inputs are supported between tessellation
295 control and tessellation evaluation shaders, not counting in TESSINNER and
296 TESSOUTER. The minimum allowed value for OpenGL is 30.
297 * ``pipe_caps.texture_float_linear``: Whether the linear minification and
298 magnification filters are supported with single-precision floating-point
299 textures.
300 * ``pipe_caps.texture_half_float_linear``: Whether the linear minification and
301 magnification filters are supported with half-precision floating-point
302 textures.
303 * ``pipe_caps.depth_bounds_test``: Whether bounds_test, bounds_min, and
304 bounds_max states of pipe_depth_stencil_alpha_state behave according
305 to the :ext:`GL_EXT_depth_bounds_test` specification.
306 * ``pipe_caps.texture_query_samples``: Whether the ``TXQS`` opcode is supported
307 * ``pipe_caps.force_persample_interp``: If the driver can force per-sample
308 interpolation for all fragment shader inputs if
309 pipe_rasterizer_state::force_persample_interp is set. This is only used
310 by GL3-level sample shading (:ext:`GL_ARB_sample_shading`). GL4-level sample
311 shading (:ext:`GL_ARB_gpu_shader5`) doesn't use this. While GL3 hardware has a
312 state for it, GL4 hardware will likely need to emulate it with a shader
313 variant, or by selecting the interpolation weights with a conditional
314 assignment in the shader.
315 * ``pipe_caps.shareable_shaders``: Whether shader CSOs can be used by any
316 pipe_context. Important for reducing jank at draw time by letting GL shaders
317 linked in one thread be used in another thread without recompiling.
318 * ``pipe_caps.copy_between_compressed_and_plain_formats``:
319 Whether copying between compressed and plain formats is supported where
320 a compressed block is copied to/from a plain pixel of the same size.
321 * ``pipe_caps.clear_scissored``: Whether ``clear`` can accept a scissored
322 bounding box.
323 * ``pipe_caps.draw_parameters``: Whether ``TGSI_SEMANTIC_BASEVERTEX``,
324 ``TGSI_SEMANTIC_BASEINSTANCE``, and ``TGSI_SEMANTIC_DRAWID`` are
325 supported in vertex shaders.
326 * ``pipe_caps.shader_pack_half_float``: Whether packed 16-bit float
327 packing/unpacking opcodes are supported.
328 * ``pipe_caps.fs_position_is_sysval``: If gallium frontends should use a
329 system value for the POSITION fragment shader input.
330 * ``pipe_caps.fs_point_is_sysval``: If gallium frontends should use a system
331 value for the POINT fragment shader input.
332 * ``pipe_caps.fs_face_is_integer_sysval``: If gallium frontends should use
333 a system value for the FACE fragment shader input.
334 Also, the FACE system value is integer, not float.
335 * ``pipe_caps.shader_buffer_offset_alignment``: Describes the required
336 alignment for pipe_shader_buffer::buffer_offset, in bytes. Maximum
337 value allowed is 256 (for GL conformance). 0 is only allowed if
338 shader buffers are not supported.
339 * ``pipe_caps.invalidate_buffer``: Whether the use of ``invalidate_resource``
340 for buffers is supported.
341 * ``pipe_caps.generate_mipmap``: Indicates whether pipe_context::generate_mipmap
342 is supported.
343 * ``pipe_caps.string_marker``: Whether pipe->emit_string_marker() is supported.
344 * ``pipe_caps.surface_no_compress``: Indicates that
345 pipe_context::create_surface does not support compression
346 * ``pipe_caps.surface_reinterpret_blocks``: Indicates whether
347 pipe_context::create_surface supports reinterpreting a texture as a surface
348 of a format with different block width/height (but same block size in bits).
349 For example, a compressed texture image can be interpreted as a
350 non-compressed surface whose texels are the same number of bits as the
351 compressed blocks, and vice versa. The width and height of the surface is
352 adjusted appropriately.
353 * ``pipe_caps.compressed_surface_reinterpret_blocks_layered``: Same as
354 ``pipe_caps.surface_reinterpret_blocks`` but for supporting multiple layers
355 of a compressed texture.
356 * ``pipe_caps.query_buffer_object``: Driver supports
357 context::get_query_result_resource callback.
358 * ``pipe_caps.pci_group``: Return the PCI segment group number.
359 * ``pipe_caps.pci_bus``: Return the PCI bus number.
360 * ``pipe_caps.pci_device``: Return the PCI device number.
361 * ``pipe_caps.pci_function``: Return the PCI function number.
362 * ``pipe_caps.framebuffer_no_attachment``:
363 If non-zero, rendering to framebuffers with no surface attachments
364 is supported. The context->is_format_supported function will be expected
365 to be implemented with PIPE_FORMAT_NONE yielding the MSAA modes the hardware
366 supports. N.B., The maximum number of layers supported for rasterizing a
367 primitive on a layer is obtained from ``pipe_caps.max_texture_array_layers``
368 even though it can be larger than the number of layers supported by either
369 rendering or textures.
370 * ``pipe_caps.robust_buffer_access_behavior``: Implementation uses bounds
371 checking on resource accesses by shader if the context is created with
372 PIPE_CONTEXT_ROBUST_BUFFER_ACCESS. See the
373 :ext:`GL_ARB_robust_buffer_access_behavior` extension for information on the
374 required behavior for out of bounds accesses and accesses to unbound
375 resources.
376 * ``pipe_caps.cull_distance``: Whether the driver supports the
377 :ext:`GL_ARB_cull_distance` extension and thus implements proper support for
378 culling planes.
379 * ``pipe_caps.primitive_restart_for_patches``: Whether primitive restart is
380 supported for patch primitives.
381 * ``pipe_caps.shader_group_vote``: Whether the ``VOTE_*`` ops can be used in
382 shaders.
383 * ``pipe_caps.max_window_rectangles``: The maximum number of window rectangles
384 supported in ``set_window_rectangles``.
385 * ``pipe_caps.viewport_subpixel_bits``: Number of bits of subpixel precision for
386 floating point viewport bounds.
387 * ``pipe_caps.rasterizer_subpixel_bits``: Number of bits of subpixel precision used
388 by the rasterizer.
389 * ``pipe_caps.mixed_color_depth_bits``: Whether there is non-fallback
390 support for color/depth format combinations that use a different
391 number of bits. For the purpose of this cap, Z24 is treated as
392 32-bit. If set to off, that means that a B5G6R5 + Z24 or RGBA8 + Z16
393 combination will require a driver fallback, and should not be
394 advertised in the GLX/EGL config list.
395 * ``pipe_caps.shader_array_components``: If true, the driver interprets the
396 UsageMask of input and output declarations and allows declaring arrays
397 in overlapping ranges. The components must be a contiguous range, e.g. a
398 UsageMask of xy or yzw is allowed, but xz or yw isn't. Declarations with
399 overlapping locations must have matching semantic names and indices, and
400 equal interpolation qualifiers.
401 Components may overlap, notably when the gaps in an array of dvec3 are
402 filled in.
403 * ``pipe_caps.stream_output_pause_resume``: Whether
404 :ext:`GL_ARB_transform_feedback2` is supported, including pausing/resuming
405 queries and having ``count_from_stream_output`` set on indirect draws to
406 implement glDrawTransformFeedback. Required for OpenGL 4.0.
407 * ``pipe_caps.stream_output_interleave_buffers``: Whether interleaved stream
408 output mode is able to interleave across buffers. This is required for
409 :ext:`GL_ARB_transform_feedback3`.
410 * ``pipe_caps.fbfetch``: The number of render targets whose value in the
411 current framebuffer can be read in the shader. 0 means framebuffer fetch
412 is not supported. 1 means that only the first render target can be read,
413 and a larger value would mean that multiple render targets are supported.
414 * ``pipe_caps.fbfetch_coherent``: Whether framebuffer fetches from the fragment
415 shader can be guaranteed to be coherent with framebuffer writes.
416 * ``pipe_caps.fbfetch_zs``: Whether fragment shader can fetch current values of
417 Z/S attachments. These fetches are always coherent with framebuffer writes.
418 * ``pipe_caps.legacy_math_rules``: Whether NIR shaders support the
419 ``shader_info.use_legacy_math_rules`` flag (see documentation there), and
420 TGSI shaders support the corresponding ``TGSI_PROPERTY_LEGACY_MATH_RULES``.
421 * ``pipe_caps.fp16``: Whether 16-bit float operations are supported.
422 * ``pipe_caps.doubles``: Whether double precision floating-point operations
423 are supported.
424 * ``pipe_caps.int64``: Whether 64-bit integer operations are supported.
425 * ``pipe_caps.tgsi_tex_txf_lz``: Whether TEX_LZ and TXF_LZ opcodes are
426 supported.
427 * ``pipe_caps.shader_clock``: Whether the CLOCK opcode is supported.
428 * ``pipe_caps.polygon_mode_fill_rectangle``: Whether the
429 PIPE_POLYGON_MODE_FILL_RECTANGLE mode is supported for
430 ``pipe_rasterizer_state::fill_front`` and
431 ``pipe_rasterizer_state::fill_back``.
432 * ``pipe_caps.sparse_buffer_page_size``: The page size of sparse buffers in
433 bytes, or 0 if sparse buffers are not supported. The page size must be at
434 most 64KB.
435 * ``pipe_caps.shader_ballot``: Whether the BALLOT and READ_* opcodes as well as
436 the SUBGROUP_* semantics are supported.
437 * ``pipe_caps.tes_layer_viewport``: Whether ``VARYING_SLOT_LAYER`` and
438 ``VARYING_SLOT_VIEWPORT`` are supported as tessellation evaluation
439 shader outputs.
440 * ``pipe_caps.can_bind_const_buffer_as_vertex``: Whether a buffer with just
441 PIPE_BIND_CONSTANT_BUFFER can be legally passed to set_vertex_buffers.
442 * ``pipe_caps.allow_mapped_buffers_during_execution``: As the name says.
443 * ``pipe_caps.post_depth_coverage``: whether
444 ``TGSI_PROPERTY_FS_POST_DEPTH_COVERAGE`` is supported.
445 * ``pipe_caps.bindless_texture``: Whether bindless texture operations are
446 supported.
447 * ``pipe_caps.nir_samplers_as_deref``: Whether NIR tex instructions should
448 reference texture and sampler as NIR derefs instead of by indices.
449 * ``pipe_caps.query_so_overflow``: Whether the
450 ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` and
451 ``PIPE_QUERY_SO_OVERFLOW_ANY_PREDICATE`` query types are supported. Note that
452 for a driver that does not support multiple output streams (i.e.,
453 ``pipe_caps.max_vertex_streams`` is 1), both query types are identical.
454 * ``pipe_caps.memobj``: Whether operations on memory objects are supported.
455 * ``pipe_caps.load_constbuf``: True if the driver supports ``TGSI_OPCODE_LOAD`` use
456 with constant buffers.
457 * ``pipe_caps.tile_raster_order``: Whether the driver supports
458 :ext:`GL_MESA_tile_raster_order`, using the tile_raster_order_* fields in
459 pipe_rasterizer_state.
460 * ``pipe_caps.max_combined_shader_output_resources``: Limit on combined shader
461 output resources (images + buffers + fragment outputs). If 0 the state
462 tracker works it out.
463 * ``pipe_caps.framebuffer_msaa_constraints``: This determines limitations
464 on the number of samples that framebuffer attachments can have.
465 Possible values:
466
467 0. color.nr_samples == zs.nr_samples == color.nr_storage_samples
468 (standard MSAA quality)
469 1. color.nr_samples >= zs.nr_samples == color.nr_storage_samples
470 (enhanced MSAA quality)
471 2. color.nr_samples >= zs.nr_samples >= color.nr_storage_samples
472 (full flexibility in tuning MSAA quality and performance)
473
474 All color attachments must have the same number of samples and the same
475 number of storage samples.
476 * ``pipe_caps.signed_vertex_buffer_offset``:
477 Whether pipe_vertex_buffer::buffer_offset is treated as signed. The u_vbuf
478 module needs this for optimal performance in workstation applications.
479 * ``pipe_caps.context_priority_mask``: For drivers that support per-context
480 priorities, this returns a bitmask of ``PIPE_CONTEXT_PRIORITY_x`` for the
481 supported priority levels. A driver that does not support prioritized
482 contexts can return 0.
483 * ``pipe_caps.fence_signal``: True if the driver supports signaling semaphores
484 using fence_server_signal().
485 * ``pipe_caps.constbuf0_flags``: The bits of pipe_resource::flags that must be
486 set when binding that buffer as constant buffer 0. If the buffer doesn't have
487 those bits set, pipe_context::set_constant_buffer(.., 0, ..) is ignored
488 by the driver, and the driver can throw assertion failures.
489 * ``pipe_caps.packed_uniforms``: True if the driver supports packed uniforms
490 as opposed to padding to vec4s. Requires ``pipe_shader_caps.integers`` if
491 ``lower_uniforms_to_ubo`` is set.
492 * ``pipe_caps.conservative_raster_post_snap_triangles``: Whether the
493 ``PIPE_CONSERVATIVE_RASTER_POST_SNAP`` mode is supported for triangles.
494 The post-snap mode means the conservative rasterization occurs after
495 the conversion from floating-point to fixed-point coordinates
496 on the subpixel grid.
497 * ``pipe_caps.conservative_raster_post_snap_points_lines``: Whether the
498 ``PIPE_CONSERVATIVE_RASTER_POST_SNAP`` mode is supported for points and lines.
499 * ``pipe_caps.conservative_raster_pre_snap_triangles``: Whether the
500 ``PIPE_CONSERVATIVE_RASTER_PRE_SNAP`` mode is supported for triangles.
501 The pre-snap mode means the conservative rasterization occurs before
502 the conversion from floating-point to fixed-point coordinates.
503 * ``pipe_caps.conservative_raster_pre_snap_points_lines``: Whether the
504 ``PIPE_CONSERVATIVE_RASTER_PRE_SNAP`` mode is supported for points and lines.
505 * ``pipe_caps.conservative_raster_post_depth_coverage``: Whether
506 ``pipe_caps.post_depth_coverage`` works with conservative rasterization.
507 * ``pipe_caps.conservative_raster_inner_coverage``: Whether
508 inner_coverage from :ext:`GL_INTEL_conservative_rasterization` is supported.
509 * ``pipe_caps.max_conservative_raster_subpixel_precision_bias``: The maximum
510 subpixel precision bias in bits during conservative rasterization.
511 * ``pipe_caps.programmable_sample_locations``: True is the driver supports
512 programmable sample location through ```get_sample_pixel_grid``` and
513 ```set_sample_locations```.
514 * ``pipe_caps.max_gs_invocations``: Maximum supported value of
515 TGSI_PROPERTY_GS_INVOCATIONS.
516 * ``pipe_caps.max_shader_buffer_size``: Maximum supported size for binding
517 with set_shader_buffers. This is unsigned integer with the maximum of 4GB - 1.
518 * ``pipe_caps.max_combined_shader_buffers``: Maximum total number of shader
519 buffers. A value of 0 means the sum of all per-shader stage maximums (see
520 ``pipe_shader_caps.max_shader_buffers``).
521 * ``pipe_caps.max_combined_hw_atomic_counters``: Maximum total number of atomic
522 counters. A value of 0 means the default value (MAX_ATOMIC_COUNTERS = 4096).
523 * ``pipe_caps.max_combined_hw_atomic_counter_buffers``: Maximum total number of
524 atomic counter buffers. A value of 0 means the sum of all per-shader stage
525 maximums (see ``pipe_shader_caps.max_hw_atomic_counter_buffers``).
526 * ``pipe_caps.max_texture_upload_memory_budget``: Maximum recommend memory size
527 for all active texture uploads combined. This is a performance hint.
528 0 means no limit.
529 * ``pipe_caps.max_vertex_element_src_offset``: The maximum supported value for
530 of pipe_vertex_element::src_offset.
531 * ``pipe_caps.surface_sample_count``: Whether the driver
532 supports pipe_surface overrides of resource nr_samples. If set, will
533 enable :ext:`GL_EXT_multisampled_render_to_texture`.
534 * ``pipe_caps.image_atomic_float_add``: Atomic floating point adds are
535 supported on images, buffers, and shared memory.
536 * ``pipe_caps.glsl_tess_levels_as_inputs``: True if the driver wants TESSINNER and TESSOUTER to be inputs (rather than system values) for tessellation evaluation shaders.
537 * ``pipe_caps.dest_surface_srgb_control``: Indicates whether the drivers
538 supports switching the format between sRGB and linear for a surface that is
539 used as destination in draw and blit calls.
540 * ``pipe_caps.max_varyings``: The maximum number of fragment shader
541 varyings. This will generally correspond to
542 ``pipe_shader_caps.max_inputs`` for the fragment shader, but in some
543 cases may be a smaller number.
544 * ``pipe_caps.compute_grid_info_last_block``: Whether pipe_grid_info::last_block
545 is implemented by the driver. See struct pipe_grid_info for more details.
546 * ``pipe_caps.compute_shader_derivative``: True if the driver supports derivatives (and texture lookups with implicit derivatives) in compute shaders.
547 * ``pipe_caps.image_load_formatted``: True if a format for image loads does not need to be specified in the shader IR
548 * ``pipe_caps.image_store_formatted``: True if a format for image stores does not need to be specified in the shader IR
549 * ``pipe_caps.throttle``: Whether or not gallium frontends should throttle pipe_context
550 execution. 0 = throttling is disabled.
551 * ``pipe_caps.dmabuf``: Whether Linux DMABUF handles are supported by
552 resource_from_handle and resource_get_handle.
553 Possible bit field values:
554
555 1. ``DRM_PRIME_CAP_IMPORT``: resource_from_handle is supported
556 2. ``DRM_PRIME_CAP_EXPORT``: resource_get_handle is supported
557
558 * ``pipe_caps.cl_gl_sharing``: True if driver supports everything required by a frontend implementing the CL extension, and
559 also supports importing/exporting all of pipe_texture_target via dma buffers.
560 * ``pipe_caps.prefer_compute_for_multimedia``: Whether VAAPI
561 should use a compute-based blit instead of pipe_context::blit and compute pipeline for compositing images.
562 * ``pipe_caps.fragment_shader_interlock``: True if fragment shader interlock
563 functionality is supported.
564 * ``pipe_caps.atomic_float_minmax``: Atomic float point minimum,
565 maximum, exchange and compare-and-swap support to buffer and shared variables.
566 * ``pipe_caps.dithering``: Whether dithering is supported
567 * ``pipe_caps.fragment_shader_texture_lod``: Whether texture lookups with
568 explicit LOD is supported in the fragment shader.
569 * ``pipe_caps.fragment_shader_derivatives``: True if the driver supports
570 derivatives in fragment shaders.
571 * ``pipe_caps.texture_shadow_lod``: True if the driver supports shadow sampler
572 types with texture functions having interaction with LOD of texture lookup.
573 * ``pipe_caps.shader_samples_identical``: True if the driver supports a shader query to tell whether all samples of a multisampled surface are definitely identical.
574 * ``pipe_caps.image_atomic_inc_wrap``: Atomic increment/decrement + wrap around
575 are supported.
576 * ``pipe_caps.prefer_imm_arrays_as_constbuf``: True if gallium frontends should
577 turn arrays whose contents can be deduced at compile time into constant
578 buffer loads, or false if the driver can handle such arrays itself in a more
579 efficient manner (such as through nir_opt_large_constants() and nir->constant_data).
580 * ``pipe_caps.gl_spirv``: True if the driver supports :ext:`GL_ARB_gl_spirv` extension.
581 * ``pipe_caps.gl_spirv_variable_pointers``: True if the driver supports Variable Pointers in SPIR-V shaders.
582 * ``pipe_caps.demote_to_helper_invocation``: True if driver supports demote keyword in GLSL programs.
583 * ``pipe_caps.tgsi_tg4_component_in_swizzle``: True if driver wants the TG4 component encoded in sampler swizzle rather than as a separate source.
584 * ``pipe_caps.flatshade``: Driver supports pipe_rasterizer_state::flatshade. Must be 1
585 for non-NIR drivers.
586 * ``pipe_caps.alpha_test``: Driver supports alpha-testing. Must be 1
587 for non-NIR drivers. If set, frontend may set
588 ``pipe_depth_stencil_alpha_state->alpha_enabled`` and ``alpha_func``.
589 Otherwise, alpha test will be lowered to a comparison and discard_if in the
590 fragment shader.
591 * ``pipe_caps.point_size_fixed``: Driver supports point-sizes that are fixed,
592 as opposed to writing gl_PointSize for every point.
593 * ``pipe_caps.two_sided_color``: Driver supports two-sided coloring. Must be 1
594 for non-NIR drivers. If set, pipe_rasterizer_state may be set to indicate
595 that back-facing primitives should use the back-side color as the FS input
596 color. If unset, mesa/st will lower it to gl_FrontFacing reads in the
597 fragment shader.
598 * ``pipe_caps.clip_planes``: Driver supports user-defined clip-planes. 0 denotes
599 none, 1 denotes MAX_CLIP_PLANES. > 1 overrides MAX. When is 0,
600 ``set_clip_state()`` will never be called. Instead, user clip planes are
601 lowered to clip distance writes to CLIP_DIST[] corresponding to
602 pipe_rasterizer_state::clip_plane_enable bits.
603 * ``pipe_caps.max_vertex_buffers``: Number of supported vertex buffers.
604 * ``pipe_caps.opencl_integer_functions``: Driver supports extended OpenCL-style integer functions. This includes average, saturating addition, saturating subtraction, absolute difference, count leading zeros, and count trailing zeros.
605 * ``pipe_caps.integer_multiply_32x16``: Driver supports integer multiplication between a 32-bit integer and a 16-bit integer. If the second operand is 32-bits, the upper 16-bits are ignored, and the low 16-bits are possibly sign extended as necessary.
606 * ``pipe_caps.nir_images_as_deref``: Whether NIR image load/store intrinsics should be nir_intrinsic_image_deref_* instead of nir_intrinsic_image_*. Defaults to true.
607 * ``pipe_caps.packed_stream_output``: Driver supports packing optimization for stream output (e.g. GL transform feedback captured variables). Defaults to true.
608 * ``pipe_caps.viewport_transform_lowered``: Driver needs the nir_lower_viewport_transform pass to be enabled. This also means that the gl_Position value is modified and should be lowered for transform feedback, if needed. Defaults to false.
609 * ``pipe_caps.psiz_clamped``: Driver needs for the point size to be clamped. Additionally, the gl_PointSize has been modified and its value should be lowered for transform feedback, if needed. Defaults to false.
610 * ``pipe_caps.gl_begin_end_buffer_size``: Buffer size used to upload vertices for glBegin/glEnd.
611 * ``pipe_caps.viewport_swizzle``: Whether pipe_viewport_state::swizzle can be used to specify pre-clipping swizzling of coordinates (see :ext:`GL_NV_viewport_swizzle`).
612 * ``pipe_caps.system_svm``: True if all application memory can be shared with the GPU without explicit mapping.
613 * ``pipe_caps.viewport_mask``: Whether ``TGSI_SEMANTIC_VIEWPORT_MASK`` and ``TGSI_PROPERTY_LAYER_VIEWPORT_RELATIVE`` are supported (see :ext:`GL_NV_viewport_array2`).
614 * ``pipe_caps.map_unsynchronized_thread_safe``: Whether mapping a buffer as unsynchronized from any thread is safe.
615 * ``pipe_caps.glsl_zero_init``: Choose a default zero initialization some GLSL variables. If ``1``, then all GLSL shader variables and gl_FragColor are initialized to zero. If ``2``, then shader out variables are not initialized but function out variables are.
616 * ``pipe_caps.blend_equation_advanced``: Driver supports blend equation advanced without necessarily supporting FBFETCH.
617 * ``pipe_caps.nir_atomics_as_deref``: Whether NIR atomics instructions should reference atomics as NIR derefs instead of by indices.
618 * ``pipe_caps.no_clip_on_copy_tex``: Driver doesn't want x/y/width/height clipped based on src size when doing a copy texture operation (e.g.: may want out-of-bounds reads that produce 0 instead of leaving the texture content undefined)
619 * ``pipe_caps.max_texture_mb``: Maximum texture size in MB (default is 1024)
620 * ``pipe_caps.device_protected_surface``: Whether the device support protected / encrypted content.
621 * ``pipe_caps.prefer_real_buffer_in_constbuf0``: The state tracker is encouraged to upload constants into a real buffer and bind it into constant buffer 0 instead of binding a user pointer. This may enable a faster code-path in a gallium frontend for drivers that really prefer a real buffer.
622 * ``pipe_caps.gl_clamp``: Driver natively supports GL_CLAMP. Required for non-NIR drivers with the GL frontend. NIR drivers with the cap unavailable will have GL_CLAMP lowered to txd/txl with a saturate on the coordinates.
623 * ``pipe_caps.texrect``: Driver supports rectangle textures. Required for OpenGL on ``!prefers_nir`` drivers. If this cap is not present, st/mesa will lower the NIR to use normal 2D texture sampling by using either ``txs`` or ``nir_intrinsic_load_texture_scaling`` to normalize the texture coordinates.
624 * ``pipe_caps.sampler_reduction_minmax``: Driver supports EXT min/max sampler reduction.
625 * ``pipe_caps.sampler_reduction_minmax_arb``: Driver supports ARB min/max sampler reduction with format queries.
626 * ``pipe_caps.emulate_nonfixed_primitive_restart``: Driver requests all draws using a non-fixed restart index to be rewritten to use a fixed restart index.
627 * ``pipe_caps.supported_prim_modes``: A bitmask of the ``mesa_prim`` enum values that the driver can natively support.
628 * ``pipe_caps.supported_prim_modes_with_restart``: A bitmask of the ``mesa_prim`` enum values that the driver can natively support for primitive restart. Only useful if ``pipe_caps.primitive_restart`` is also exported.
629 * ``pipe_caps.prefer_back_buffer_reuse``: Only applies to DRI_PRIME. If 1, the driver prefers that DRI3 tries to use the same back buffer each frame. If 0, this means DRI3 will at least use 2 back buffers and ping-pong between them to allow the tiled->linear copy to run in parallel.
630 * ``pipe_caps.draw_vertex_state``: Driver supports ``pipe_screen::create_vertex_state/vertex_state_destroy`` and ``pipe_context::draw_vertex_state``. Only used by display lists and designed to serve vbo_save.
631 * ``pipe_caps.prefer_pot_aligned_varyings``: Driver prefers varyings to be aligned to power of two in a slot. If this cap is enabled, vec4 varying will be placed in .xyzw components of the varying slot, vec3 in .xyz and vec2 in .xy or .zw
632 * ``pipe_caps.max_sparse_texture_size``: Maximum 1D/2D/rectangle texture image dimension for a sparse texture.
633 * ``pipe_caps.max_sparse_3d_texture_size``: Maximum 3D texture image dimension for a sparse texture.
634 * ``pipe_caps.max_sparse_array_texture_layers``: Maximum number of layers in a sparse array texture.
635 * ``pipe_caps.sparse_texture_full_array_cube_mipmaps``: TRUE if there are no restrictions on the allocation of mipmaps in sparse textures and FALSE otherwise. See SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB description in :ext:`GL_ARB_sparse_texture` extension spec.
636 * ``pipe_caps.query_sparse_texture_residency``: TRUE if shader sparse texture sample instruction could also return the residency information.
637 * ``pipe_caps.clamp_sparse_texture_lod``: TRUE if shader sparse texture sample instruction support clamp the minimal lod to prevent read from uncommitted pages.
638 * ``pipe_caps.allow_draw_out_of_order``: TRUE if the driver allows the "draw out of order" optimization to be enabled. See _mesa_update_allow_draw_out_of_order for more details.
639 * ``pipe_caps.max_constant_buffer_size``: Maximum bound constant buffer size in bytes. This is unsigned integer with the maximum of 4GB - 1. This applies to all constant buffers used by UBOs, unlike ``pipe_shader_caps.max_const_buffer0_size``, which is specifically for GLSL uniforms.
640 * ``pipe_caps.hardware_gl_select``: Enable hardware accelerated GL_SELECT for this driver.
641 * ``pipe_caps.device_protected_context``: Whether the device supports protected / encrypted context which can manipulate protected / encrypted content (some devices might need protected contexts to access protected content, whereas ``pipe_caps.device_protected_surface`` does not require any particular context to do so).
642 * ``pipe_caps.allow_glthread_buffer_subdata_opt``: Whether to allow glthread to convert glBufferSubData to glCopyBufferSubData. This may improve or worsen performance depending on your driver.
643 * ``pipe_caps.null_textures`` : Whether the driver supports sampling from NULL textures.
644 * ``pipe_caps.astc_void_extents_need_denorm_flush`` : True if the driver/hardware needs denormalized values in ASTC void extent blocks flushed to zero.
645 * ``pipe_caps.validate_all_dirty_states`` : Whether state validation must also validate the state changes for resources types used in the previous shader but not in the current shader.
646 * ``pipe_caps.has_const_bw``: Whether the driver only supports non-data-dependent layouts (ie. not bandwidth compressed formats like AFBC, UBWC, etc), or supports ``PIPE_BIND_CONST_BW`` to disable data-dependent layouts on requested resources.
647 * ``pipe_caps.performance_monitor``: Whether GL_AMD_performance_monitor should be exposed.
648 * ``pipe_caps.texture_sampler_independent``: Whether sampler views and sampler states are independent objects, meaning both can be freely mixed and matched by the frontend. This isn't required for OpenGL where on the shader level those are the same object. However for proper OpenCL support this is required.
649 * ``pipe_caps.astc_decode_mode``: Whether the driver supports ASTC decode precision. The :ext:`GL_EXT_texture_compression_astc_decode_mode` extension will only get exposed if :ext:`GL_KHR_texture_compression_astc_ldr<GL_KHR_texture_compression_astc_hdr>` is also supported.
650 * ``pipe_caps.shader_subgroup_size``: A fixed subgroup size shader runs on GPU when GLSL GL_KHR_shader_subgroup_* extensions are enabled.
651 * ``pipe_caps.shader_subgroup_supported_stages``: Bitmask of shader stages which support GL_KHR_shader_subgroup_* intrinsics.
652 * ``pipe_caps.shader_subgroup_supported_features``: Bitmask of shader subgroup features listed in :ext:`GL_KHR_shader_subgroup`.
653 * ``pipe_caps.shader_subgroup_quad_all_stages``: Whether shader subgroup quad operations are supported by shader stages other than fragment shader.
654 * ``pipe_caps.multiview``: Whether multiview rendering of array textures is supported. A return of ``1`` indicates support for OVR_multiview, and ``2`` additionally supports OVR_multiview2.
655 * ``pipe_caps.call_finalize_nir_in_linker``: Whether ``pipe_screen::finalize_nir`` can be called in the GLSL linker before the NIR is stored in the shader cache. It's always called again after st/mesa adds code for shader variants. It must be 1 if the driver wants to report compile failures to the GLSL linker. It must be 0 if two consecutive ``finalize_nir`` calls on the same shader can break it, or if ``finalize_nir`` can't handle NIR that isn't fully lowered for the driver, or if ``finalize_nir`` breaks passes that st/mesa runs after it. Setting it to 1 is generally safe for drivers that expose nir_io_has_intrinsics and that don't enable any optional shader variants in st/mesa. Since it's difficult to support, any future refactoring can change it to 0.
656 * ``pipe_caps.representative_fragment_test``: Support for GL_NV_representative_fragment_test.
657 * ``pipe_caps.min_line_width``: The minimum width of a regular line.
658 * ``pipe_caps.min_line_width_aa``: The minimum width of a smoothed line.
659 * ``pipe_caps.max_line_width``: The maximum width of a regular line.
660 * ``pipe_caps.max_line_width_aa``: The maximum width of a smoothed line.
661 * ``pipe_caps.line_width_granularity``: The line width is rounded to a multiple of this number.
662 * ``pipe_caps.min_point_size``: The minimum width and height of a point.
663 * ``pipe_caps.min_point_size_aa``: The minimum width and height of a smoothed point.
664 * ``pipe_caps.max_point_size``: The maximum width and height of a point.
665 * ``pipe_caps.max_point_size_aa``: The maximum width and height of a smoothed point.
666 * ``pipe_caps.point_size_granularity``: The point size is rounded to a multiple of this number.
667 * ``pipe_caps.max_texture_anisotropy``: The maximum level of anisotropy that can be
668 applied to anisotropically filtered textures.
669 * ``pipe_caps.max_texture_lod_bias``: The maximum :term:`LOD` bias that may be applied
670 to filtered textures.
671 * ``pipe_caps.min_conservative_raster_dilate``: The minimum conservative rasterization
672 dilation.
673 * ``pipe_caps.max_conservative_raster_dilate``: The maximum conservative rasterization
674 dilation.
675 * ``pipe_caps.conservative_raster_dilate_granularity``: The conservative rasterization
676 dilation granularity for values relative to the minimum dilation.
677 * ``pipe_caps.clear_masked``: Whether ``clear`` can accept a color_clear_mask for all color buffers and stencil_clear_mask.
678 * ``pipe_caps.prefer_persp``: Whether the driver prefers perspective correct
679 or linear interpolation. This is a performance hint.
680 * ``pipe_caps.blit_3d``: Whether pipe_context::blit can have depth > 1.
681
682
683 .. _pipe_shader_caps:
684
685 pipe_shader_caps
686 ^^^^^^^^^^^^^^^^^
687
688 These are per-shader-stage capabitity queries. Different shader stages may
689 support different features.
690
691 * ``pipe_shader_caps.max_instructions``: The maximum number of instructions.
692 * ``pipe_shader_caps.max_alu_instructions``: The maximum number of arithmetic instructions.
693 * ``pipe_shader_caps.max_tex_instructions``: The maximum number of texture instructions.
694 * ``pipe_shader_caps.max_tex_indirections``: The maximum number of texture indirections.
695 * ``pipe_shader_caps.max_control_flow_depth``: The maximum nested control flow depth.
696 * ``pipe_shader_caps.max_inputs``: The maximum number of input registers.
697 * ``pipe_shader_caps.max_outputs``: The maximum number of output registers.
698 This is valid for all shaders except the fragment shader.
699 * ``pipe_shader_caps.max_const_buffer0_size``: The maximum size of constant buffer 0 in bytes.
700 * ``pipe_shader_caps.max_const_buffers``: Maximum number of constant buffers that can be bound
701 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
702 only permit binding one constant buffer per shader.
703
704 If a value greater than 0 is returned, the driver can have multiple
705 constant buffers bound to shader stages. The CONST register file is
706 accessed with two-dimensional indices, like in the example below.
707
708 ::
709
710 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
711 DCL CONST[3][0] # declare first vector of constbuf 3
712 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
713
714 * ``pipe_shader_caps.max_temps``: The maximum number of temporary registers.
715 * ``pipe_shader_caps.cont_supported``: Whether continue is supported.
716 * ``pipe_shader_caps.indirect_temp_addr``: Whether indirect addressing
717 of the temporary file is supported.
718 * ``pipe_shader_caps.indirect_const_addr``: Whether indirect addressing
719 of the constant file is supported.
720 * ``pipe_shader_caps.subroutines``: Whether subroutines are supported, i.e.
721 BGNSUB, ENDSUB, CAL, and RET, including RET in the main block.
722 * ``pipe_shader_caps.integers``: Whether integer opcodes are supported.
723 If unsupported, only float opcodes are supported.
724 * ``pipe_shader_caps.int64_atomics``: Whether int64 atomic opcodes are supported. The device needs to support add, sub, swap, cmpswap, and, or, xor, min, and max.
725 * ``pipe_shader_caps.fp16``: Whether half precision floating-point opcodes are supported.
726 If unsupported, half precision ops need to be lowered to full precision.
727 * ``pipe_shader_caps.fp16_derivatives``: Whether half precision floating-point
728 DDX and DDY opcodes are supported.
729 * ``pipe_shader_caps.fp16_const_buffers``: Whether half precision floating-point
730 constant buffer loads are supported. Drivers are recommended to report 0
731 if x86 F16C is not supported by the CPU (or an equivalent instruction set
732 on other CPU architectures), otherwise they could be impacted by emulated
733 FP16 conversions in glUniform.
734 * ``pipe_shader_caps.int16``: Whether 16-bit signed and unsigned integer types
735 are supported.
736 * ``pipe_shader_caps.glsl_16bit_consts``: Lower mediump constants to 16-bit.
737 Note that 16-bit constants are not lowered to uniforms in GLSL.
738 * ``pipe_shader_caps.max_texture_samplers``: The maximum number of texture
739 samplers.
740 * ``pipe_shader_caps.max_sampler_views``: The maximum number of texture
741 sampler views. Must not be lower than pipe_shader_caps.max_texture_samplers.
742 * ``pipe_shader_caps.tgsi_any_inout_decl_range``: Whether the driver doesn't
743 ignore tgsi_declaration_range::Last for shader inputs and outputs.
744 * ``pipe_shader_caps.max_shader_buffers``: Maximum number of memory buffers
745 (also used to implement atomic counters). Having this be non-0 also
746 implies support for the ``LOAD``, ``STORE``, and ``ATOM*`` TGSI
747 opcodes.
748 * ``pipe_shader_caps.supported_irs``: Supported representations of the
749 program. It should be a mask of ``pipe_shader_ir`` bits.
750 * ``pipe_shader_caps.max_shader_images``: Maximum number of image units.
751 * ``pipe_shader_caps.max_hw_atomic_counters``: If atomic counters are separate,
752 how many HW counters are available for this stage. (0 uses SSBO atomics).
753 * ``pipe_shader_caps.max_hw_atomic_counter_buffers``: If atomic counters are
754 separate, how many atomic counter buffers are available for this stage.
755
756 .. _pipe_compute_caps:
757
758 pipe_compute_caps
759 ^^^^^^^^^^^^^^^^^^
760
761 Compute-specific capabilities. They can be queried using
762 pipe_screen::get_compute_param.
763
764 * ``pipe_compute_caps.grid_dimension``: Number of supported dimensions
765 for grid and block coordinates.
766 * ``pipe_compute_caps.max_grid_size``: Maximum grid size in block
767 units.
768 * ``pipe_compute_caps.max_block_size``: Maximum block size in thread
769 units.
770 * ``pipe_compute_caps.max_threads_per_block``: Maximum number of threads that
771 a single block can contain.
772 This may be less than the product of the components of MAX_BLOCK_SIZE and is
773 usually limited by the number of threads that can be resident simultaneously
774 on a compute unit.
775 * ``pipe_compute_caps.max_global_size``: Maximum size of the GLOBAL
776 resource.
777 * ``pipe_compute_caps.max_local_size``: Maximum size of the LOCAL
778 resource.
779 * ``pipe_compute_caps.max_mem_alloc_size``: Maximum size of a memory object
780 allocation in bytes.
781 * ``pipe_compute_caps.max_clock_frequency``: Maximum frequency of the GPU
782 clock in MHz
783 * ``pipe_compute_caps.max_compute_units``: Maximum number of compute units
784 * ``pipe_compute_caps.max_subgroups``: The max amount of subgroups there can be
785 inside a block. Non 0 indicates support for OpenCL subgroups including
786 implementing ``get_compute_state_subgroup_size`` if multiple subgroup sizes
787 are supported.
788 * ``pipe_compute_caps.subgroup_sizes``: Ored power of two sizes of a basic execution
789 unit in threads. Also known as wavefront size, warp size or SIMD width.
790 E.g. ``64 | 32``.
791 * ``pipe_compute_caps.address_bits``: The default compute device address space
792 size specified as an unsigned integer value in bits.
793 * ``pipe_compute_caps.max_variable_threads_per_block``: Maximum variable number
794 of threads that a single block can contain. This is similar to
795 pipe_compute_caps.max_threads_per_block, except that the variable size is not
796 known a compile-time but at dispatch-time.
797
798 .. _pipe_bind:
799
800 PIPE_BIND_*
801 ^^^^^^^^^^^
802
803 These flags indicate how a resource will be used and are specified at resource
804 creation time. Resources may be used in different roles
805 during their life cycle. Bind flags are cumulative and may be combined to create
806 a resource which can be used for multiple things.
807 Depending on the pipe driver's memory management and these bind flags,
808 resources might be created and handled quite differently.
809
810 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
811 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs
812 must have this flag set.
813 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
814 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
815 have this flag set.
816 * ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to
817 query whether a device supports blending for a given format.
818 If this flag is set, surface creation may fail if blending is not supported
819 for the specified format. If it is not set, a driver may choose to ignore
820 blending on surfaces with formats that would require emulation.
821 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
822 pipe_screen::flush_front_buffer must have this flag set.
823 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
824 or vertex shader.
825 * ``PIPE_BIND_SAMPLER_VIEW_SUBOPTIMAL``: A hint to go along with ``PIPE_BIND_SAMPLER_VIEW``
826 that we'd like to use a particular format (ie. for zero-copy import) even if
827 it is not optimal from a hw standpoint.
828 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
829 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
830 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
831 * ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer.
832 * ``PIPE_BIND_CUSTOM``:
833 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
834 * ``PIPE_BIND_SHARED``: A shareable buffer that can be given to another
835 process.
836 * ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global
837 address space of a compute program.
838 * ``PIPE_BIND_SHADER_BUFFER``: A buffer without a format that can be bound
839 to a shader and can be used with load, store, and atomic instructions.
840 * ``PIPE_BIND_SHADER_IMAGE``: A buffer or texture with a format that can be
841 bound to a shader and can be used with load, store, and atomic instructions.
842 * ``PIPE_BIND_OPENCL``: Potentially higher precision requirements than gl/vk.
843 Float values need to be 1.5 (FULL_PROFILE) or 2.0 (EMBEDDED_PROFILE) ULPs
844 precise. For float to int conversion, the preferred rounding mode is "to
845 nearest" and if a different rounding mode is chosen, the absolute error
846 must be <= 0.6. Details can be found here:
847 https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_C.html#conversion-rules
848 * ``PIPE_BIND_COMMAND_ARGS_BUFFER``: A buffer that may be sourced by the
849 GPU command processor. It can contain, for example, the arguments to
850 indirect draw calls.
851
852 .. _pipe_usage:
853
854 PIPE_USAGE_*
855 ^^^^^^^^^^^^
856
857 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
858 Note that drivers must always support read and write CPU access at any time
859 no matter which hint they got.
860
861 * ``PIPE_USAGE_DEFAULT``: Optimized for fast GPU access.
862 * ``PIPE_USAGE_IMMUTABLE``: Optimized for fast GPU access and the resource is
863 not expected to be mapped or changed (even by the GPU) after the first upload.
864 * ``PIPE_USAGE_DYNAMIC``: Expect frequent write-only CPU access. What is
865 uploaded is expected to be used at least several times by the GPU.
866 * ``PIPE_USAGE_STREAM``: Expect frequent write-only CPU access. What is
867 uploaded is expected to be used only once by the GPU.
868 * ``PIPE_USAGE_STAGING``: Optimized for fast CPU access.
869
870
871 Methods
872 -------
873
874 XXX to-do
875
876 get_name
877 ^^^^^^^^
878
879 Returns an identifying name for the screen.
880
881 The returned string should remain valid and immutable for the lifetime of
882 pipe_screen.
883
884 get_vendor
885 ^^^^^^^^^^
886
887 Returns the screen vendor.
888
889 The returned string should remain valid and immutable for the lifetime of
890 pipe_screen.
891
892 get_device_vendor
893 ^^^^^^^^^^^^^^^^^
894
895 Returns the actual vendor of the device driving the screen
896 (as opposed to the driver vendor).
897
898 The returned string should remain valid and immutable for the lifetime of
899 pipe_screen.
900
901 context_create
902 ^^^^^^^^^^^^^^
903
904 Create a pipe_context.
905
906 **priv** is private data of the caller, which may be put to various
907 unspecified uses, typically to do with implementing swapbuffers
908 and/or front-buffer rendering.
909
910 is_format_supported
911 ^^^^^^^^^^^^^^^^^^^
912
913 Determine if a resource in the given format can be used in a specific manner.
914
915 **format** the resource format
916
917 **target** one of the PIPE_TEXTURE_x flags
918
919 **sample_count** the number of samples. 0 and 1 mean no multisampling,
920 the maximum allowed legal value is 32.
921
922 **storage_sample_count** the number of storage samples. This must be <=
923 sample_count. See the documentation of ``pipe_resource::nr_storage_samples``.
924
925 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
926
927 Returns TRUE if all usages can be satisfied.
928
929
930 can_create_resource
931 ^^^^^^^^^^^^^^^^^^^
932
933 Check if a resource can actually be created (but don't actually allocate any
934 memory). This is used to implement OpenGL's proxy textures. Typically, a
935 driver will simply check if the total size of the given resource is less than
936 some limit.
937
938 For PIPE_TEXTURE_CUBE, the pipe_resource::array_size field should be 6.
939
940
941 .. _resource_create:
942
943 resource_create
944 ^^^^^^^^^^^^^^^
945
946 Create a new resource from a template.
947 The following fields of the pipe_resource must be specified in the template:
948
949 **target** one of the pipe_texture_target enums.
950 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
951 Modern APIs allow using buffers as shader resources.
952
953 **format** one of the pipe_format enums.
954
955 **width0** the width of the base mip level of the texture or size of the buffer.
956
957 **height0** the height of the base mip level of the texture
958 (1 for 1D or 1D array textures).
959
960 **depth0** the depth of the base mip level of the texture
961 (1 for everything else).
962
963 **array_size** the array size for 1D and 2D array textures.
964 For cube maps this must be 6, for other textures 1.
965
966 **last_level** the last mip map level present.
967
968 **nr_samples**: Number of samples determining quality, driving the rasterizer,
969 shading, and framebuffer. It is the number of samples seen by the whole
970 graphics pipeline. 0 and 1 specify a resource which isn't multisampled.
971
972 **nr_storage_samples**: Only color buffers can set this lower than nr_samples.
973 Multiple samples within a pixel can have the same color. ``nr_storage_samples``
974 determines how many slots for different colors there are per pixel.
975 If there are not enough slots to store all sample colors, some samples will
976 have an undefined color (called "undefined samples").
977
978 The resolve blit behavior is driver-specific, but can be one of these two:
979
980 1. Only defined samples will be averaged. Undefined samples will be ignored.
981 2. Undefined samples will be approximated by looking at surrounding defined
982 samples (even in different pixels).
983
984 Blits and MSAA texturing: If the sample being fetched is undefined, one of
985 the defined samples is returned instead.
986
987 Sample shading (``set_min_samples``) will operate at a sample frequency that
988 is at most ``nr_storage_samples``. Greater ``min_samples`` values will be
989 replaced by ``nr_storage_samples``.
990
991 **usage** one of the :ref:`PIPE_USAGE` flags.
992
993 **bind** bitmask of the :ref:`PIPE_BIND` flags.
994
995 **flags** bitmask of PIPE_RESOURCE_FLAG flags.
996
997 **next**: Pointer to the next plane for resources that consist of multiple
998 memory planes.
999
1000 As a corollary, this mean resources for an image with multiple planes have
1001 to be created starting from the highest plane.
1002
1003 resource_changed
1004 ^^^^^^^^^^^^^^^^
1005
1006 Mark a resource as changed so derived internal resources will be recreated
1007 on next use.
1008
1009 When importing external images that can't be directly used as texture sampler
1010 source, internal copies may have to be created that the hardware can sample
1011 from. When those resources are reimported, the image data may have changed, and
1012 the previously derived internal resources must be invalidated to avoid sampling
1013 from old copies.
1014
1015
1016
1017 resource_destroy
1018 ^^^^^^^^^^^^^^^^
1019
1020 Destroy a resource. A resource is destroyed if it has no more references.
1021
1022 resource_get_address
1023 ^^^^^^^^^^^^^^^^^^^^
1024
1025 Returns the address of **resource** created with
1026 ``PIPE_RESOURCE_FLAG_FIXED_ADDRESS``.
1027
1028 get_timestamp
1029 ^^^^^^^^^^^^^
1030
1031 Query a timestamp in nanoseconds. The returned value should match
1032 PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't
1033 wait for rendering to complete (which cannot be achieved with queries).
1034
1035
1036
1037 get_driver_query_info
1038 ^^^^^^^^^^^^^^^^^^^^^
1039
1040 Return a driver-specific query. If the **info** parameter is NULL,
1041 the number of available queries is returned. Otherwise, the driver
1042 query at the specified **index** is returned in **info**.
1043 The function returns non-zero on success.
1044 The driver-specific query is described with the pipe_driver_query_info
1045 structure.
1046
1047 get_driver_query_group_info
1048 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1049
1050 Return a driver-specific query group. If the **info** parameter is NULL,
1051 the number of available groups is returned. Otherwise, the driver
1052 query group at the specified **index** is returned in **info**.
1053 The function returns non-zero on success.
1054 The driver-specific query group is described with the
1055 pipe_driver_query_group_info structure.
1056
1057
1058
1059 get_disk_shader_cache
1060 ^^^^^^^^^^^^^^^^^^^^^
1061
1062 Returns a pointer to a driver-specific on-disk shader cache. If the driver
1063 failed to create the cache or does not support an on-disk shader cache NULL is
1064 returned. The callback itself may also be NULL if the driver doesn't support
1065 an on-disk shader cache.
1066
1067
1068 is_dmabuf_modifier_supported
1069 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1070
1071 Query whether the driver supports a **modifier** in combination with a
1072 **format**, and whether it is only supported with "external" texture targets.
1073 If the combination is supported in any fashion, true is returned. If the
1074 **external_only** parameter is not NULL, the bool it points to is set to
1075 false if non-external texture targets are supported with the specified modifier+
1076 format, or true if only external texture targets are supported.
1077
1078
1079 get_dmabuf_modifier_planes
1080 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1081
1082 Query the number of planes required by the image layout specified by the
1083 **modifier** and **format** parameters. The value returned includes both planes
1084 dictated by **format** and any additional planes required for driver-specific
1085 auxiliary data necessary for the layout defined by **modifier**.
1086 If the proc is NULL, no auxiliary planes are required for any layout supported by
1087 **screen** and the number of planes can be derived directly from **format**.
1088
1089
1090 Thread safety
1091 -------------
1092
1093 Screen methods are required to be thread safe. While gallium rendering
1094 contexts are not required to be thread safe, it is required to be safe to use
1095 different contexts created with the same screen in different threads without
1096 locks. It is also required to be safe using screen methods in a thread, while
1097 using one of its contexts in another (without locks).