[mesa.git] / docs / gallium / screen.rst
1 .. _screen:
3 Screen
4 ======
6 A screen is an object representing the context-independent part of a device.
8 Flags and enumerations
9 ----------------------
11 XXX some of these don't belong in this section.
14 .. _pipe_cap:
17 ^^^^^^^^^^
19 Capability queries return information about the features and limits of the
20 driver/GPU. For floating-point values, use :ref:`get_paramf`, and for boolean
21 or integer values, use :ref:`get_param`.
23 The integer capabilities:
25 * ``PIPE_CAP_GRAPHICS``: Whether graphics is supported. If not, contexts can
26 only be created with PIPE_CONTEXT_COMPUTE_ONLY.
27 * ``PIPE_CAP_NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
28 normalized coordinates, and mipmaps.
29 * ``PIPE_CAP_MAX_DUAL_SOURCE_RENDER_TARGETS``: How many dual-source blend RTs are support.
30 :ref:`Blend` for more information.
31 * ``PIPE_CAP_ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
32 * ``PIPE_CAP_POINT_SPRITE``: Whether point sprites are available.
33 * ``PIPE_CAP_MAX_RENDER_TARGETS``: The maximum number of render targets that may be
34 bound.
35 * ``PIPE_CAP_OCCLUSION_QUERY``: Whether occlusion queries are available.
36 * ``PIPE_CAP_QUERY_TIME_ELAPSED``: Whether PIPE_QUERY_TIME_ELAPSED queries are available.
37 * ``PIPE_CAP_TEXTURE_SHADOW_MAP``: indicates whether the fragment shader hardware
38 can do the depth texture / Z comparison operation in TEX instructions
39 for shadow testing.
40 * ``PIPE_CAP_TEXTURE_SWIZZLE``: Whether swizzling through sampler views is
41 supported.
42 * ``PIPE_CAP_MAX_TEXTURE_2D_SIZE``: The maximum size of 2D (and 1D) textures.
43 * ``PIPE_CAP_MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
44 for a 3D texture.
45 * ``PIPE_CAP_MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
46 for a cubemap.
47 * ``PIPE_CAP_TEXTURE_MIRROR_CLAMP_TO_EDGE``: Whether mirrored texture coordinates are
48 supported with the clamp-to-edge wrap mode.
49 * ``PIPE_CAP_TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates are supported
50 with clamp or clamp-to-border wrap modes.
51 * ``PIPE_CAP_BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
52 from color blend equations, in :ref:`Blend` state.
53 * ``PIPE_CAP_MAX_STREAM_OUTPUT_BUFFERS``: The maximum number of stream buffers.
54 * ``PIPE_CAP_PRIMITIVE_RESTART``: Whether primitive restart is supported.
56 PRIMITIVE_RESTART where the restart index is always the fixed maximum
57 value for the index type.
58 * ``PIPE_CAP_INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
59 masks are supported. If 0, then the first rendertarget's blend mask is
60 replicated across all MRTs.
61 * ``PIPE_CAP_INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
62 available. If 0, then the first rendertarget's blend functions affect all
63 MRTs.
64 * ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS``: The maximum number of texture array
65 layers supported. If 0, the array textures are not supported at all and
66 the ARRAY texture targets are invalid.
67 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
68 FS_COORD_ORIGIN with value UPPER_LEFT is supported.
69 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
70 FS_COORD_ORIGIN with value LOWER_LEFT is supported.
72 property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
74 property FS_COORD_PIXEL_CENTER with value INTEGER is supported.
75 * ``PIPE_CAP_DEPTH_CLIP_DISABLE``: Whether the driver is capable of disabling
76 depth clipping (=1) (through pipe_rasterizer_state) or supports lowering
77 depth_clamp in the client shader code (=2), for this the driver must
78 currently use TGSI.
79 * ``PIPE_CAP_DEPTH_CLIP_DISABLE_SEPARATE``: Whether the driver is capable of
80 disabling depth clipping (through pipe_rasterizer_state) separately for
81 the near and far plane. If not, depth_clip_near and depth_clip_far will be
82 equal.
83 * ``PIPE_CAP_SHADER_STENCIL_EXPORT``: Whether a stencil reference value can be
84 written from a fragment shader.
86 in the vertex shader.
87 * ``PIPE_CAP_VERTEX_ELEMENT_INSTANCE_DIVISOR``: Whether the driver supports
88 per-instance vertex attribs.
89 * ``PIPE_CAP_FRAGMENT_COLOR_CLAMPED``: Whether fragment color clamping is
90 supported. That is, is the pipe_rasterizer_state::clamp_fragment_color
91 flag supported by the driver? If not, gallium frontends will insert
92 clamping code into the fragment shaders when needed.
94 * ``PIPE_CAP_MIXED_COLORBUFFER_FORMATS``: Whether mixed colorbuffer formats are
95 supported, e.g. RGBA8 and RGBA32F as the first and second colorbuffer, resp.
96 * ``PIPE_CAP_VERTEX_COLOR_UNCLAMPED``: Whether the driver is capable of
97 outputting unclamped vertex colors from a vertex shader. If unsupported,
98 the vertex colors are always clamped. This is the default for DX9 hardware.
99 * ``PIPE_CAP_VERTEX_COLOR_CLAMPED``: Whether the driver is capable of
100 clamping vertex colors when they come out of a vertex shader, as specified
101 by the pipe_rasterizer_state::clamp_vertex_color flag. If unsupported,
102 the vertex colors are never clamped. This is the default for DX10 hardware.
103 If both clamped and unclamped CAPs are supported, the clamping can be
104 controlled through pipe_rasterizer_state. If the driver cannot do vertex
105 color clamping, gallium frontends may insert clamping code into the vertex
106 shader.
107 * ``PIPE_CAP_GLSL_FEATURE_LEVEL``: Whether the driver supports features
108 equivalent to a specific GLSL version. E.g. for GLSL 1.3, report 130.
109 * ``PIPE_CAP_GLSL_FEATURE_LEVEL_COMPATIBILITY``: Whether the driver supports
110 features equivalent to a specific GLSL version including all legacy OpenGL
111 features only present in the OpenGL compatibility profile.
112 The only legacy features that Gallium drivers must implement are
113 the legacy shader inputs and outputs (colors, texcoords, fog, clipvertex,
114 edgeflag).
115 * ``PIPE_CAP_ESSL_FEATURE_LEVEL``: An optional cap to allow drivers to
116 report a higher GLSL version for GLES contexts. This is useful when a
117 driver does not support all the required features for a higher GL version,
118 but does support the required features for a higher GLES version. A driver
119 is allowed to return ``0`` in which case ``PIPE_CAP_GLSL_FEATURE_LEVEL`` is
120 used.
121 Note that simply returning the same value as the GLSL feature level cap is
122 incorrect. For example, GLSL version 3.30 does not require ``ARB_gpu_shader5``,
123 but ESSL version 3.20 es does require ``EXT_gpu_shader5``
125 the flatshade_first setting in ``pipe_rasterizer_state``.
126 * ``PIPE_CAP_USER_VERTEX_BUFFERS``: Whether the driver supports user vertex
127 buffers. If not, gallium frontends must upload all data which is not in hw
128 resources. If user-space buffers are supported, the driver must also still
129 accept HW resource buffers.
131 limitation. If true, pipe_vertex_buffer::buffer_offset must always be aligned
132 to 4. If false, there are no restrictions on the offset.
134 limitation. If true, pipe_vertex_buffer::stride must always be aligned to 4.
135 If false, there are no restrictions on the stride.
137 a hw limitation. If true, pipe_vertex_element::src_offset must always be
138 aligned to 4. If false, there are no restrictions on src_offset.
139 * ``PIPE_CAP_COMPUTE``: Whether the implementation supports the
140 compute entry points defined in pipe_context and pipe_screen.
141 * ``PIPE_CAP_CONSTANT_BUFFER_OFFSET_ALIGNMENT``: Describes the required
142 alignment of pipe_constant_buffer::buffer_offset.
143 * ``PIPE_CAP_START_INSTANCE``: Whether the driver supports
144 pipe_draw_info::start_instance.
146 the pipe_screen::get_timestamp hook are implemented.
147 * ``PIPE_CAP_TEXTURE_MULTISAMPLE``: Whether all MSAA resources supported
148 for rendering are also supported for texturing.
149 * ``PIPE_CAP_MIN_MAP_BUFFER_ALIGNMENT``: The minimum alignment that should be
150 expected for a pointer returned by transfer_map if the resource is
151 PIPE_BUFFER. In other words, the pointer returned by transfer_map is
152 always aligned to this value.
153 * ``PIPE_CAP_TEXTURE_BUFFER_OFFSET_ALIGNMENT``: Describes the required
154 alignment for pipe_sampler_view::u.buf.offset, in bytes.
155 If a driver does not support offset/size, it should return 0.
156 * ``PIPE_CAP_BUFFER_SAMPLER_VIEW_RGBA_ONLY``: Whether the driver only
157 supports R, RG, RGB and RGBA formats for PIPE_BUFFER sampler views.
158 When this is the case it should be assumed that the swizzle parameters
159 in the sampler view have no effect.
160 * ``PIPE_CAP_TGSI_TEXCOORD``: This CAP describes a hw limitation.
161 If true, the hardware cannot replace arbitrary shader inputs with sprite
162 coordinates and hence the inputs that are desired to be replaceable must
164 The rasterizer's sprite_coord_enable state therefore also applies to the
165 TEXCOORD semantic.
166 Also, TGSI_SEMANTIC_PCOORD becomes available, which labels a fragment shader
167 input that will always be replaced with sprite coordinates.
168 * ``PIPE_CAP_PREFER_BLIT_BASED_TEXTURE_TRANSFER``: Whether it is preferable
169 to use a blit to implement a texture transfer which needs format conversions
170 and swizzling in gallium frontends. Generally, all hardware drivers with
171 dedicated memory should return 1 and all software rasterizers should return 0.
173 is supported.
174 * ``PIPE_CAP_TEXTURE_BORDER_COLOR_QUIRK``: Bitmask indicating whether special
175 considerations have to be given to the interaction between the border color
176 in the sampler object and the sampler view used with it.
177 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_R600 is set, the border color
178 may be affected in undefined ways for any kind of permutational swizzle
179 (any swizzle XYZW where X/Y/Z/W are not ZERO, ONE, or R/G/B/A respectively)
180 in the sampler view.
181 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_NV50 is set, the border color
182 state should be swizzled manually according to the swizzle in the sampler
183 view it is intended to be used with, or herein undefined results may occur
184 for permutational swizzles.
185 * ``PIPE_CAP_MAX_TEXTURE_BUFFER_SIZE``: The maximum accessible size with
186 a buffer sampler view, in texels.
187 * ``PIPE_CAP_MAX_VIEWPORTS``: The maximum number of viewports (and scissors
188 since they are linked) a driver can support. Returning 0 is equivalent
189 to returning 1 because every driver has to support at least a single
190 viewport/scissor combination.
191 * ``PIPE_CAP_ENDIANNESS``:: The endianness of the device. Either
193 * ``PIPE_CAP_MIXED_FRAMEBUFFER_SIZES``: Whether it is allowed to have
194 different sizes for fb color/zs attachments. This controls whether
195 ARB_framebuffer_object is provided.
197 ``TGSI_SEMANTIC_VIEWPORT_INDEX`` are supported as vertex shader
198 outputs. Note that the viewport will only be used if multiple viewports are
199 exposed.
200 * ``PIPE_CAP_MAX_GEOMETRY_OUTPUT_VERTICES``: The maximum number of vertices
201 output by a single invocation of a geometry shader.
203 vertex components output by a single invocation of a geometry shader.
204 This is the product of the number of attribute components per vertex and
205 the number of output vertices.
206 * ``PIPE_CAP_MAX_TEXTURE_GATHER_COMPONENTS``: Max number of components
207 in format that texture gather can operate on. 1 == RED, ALPHA etc,
208 4 == All formats.
209 * ``PIPE_CAP_TEXTURE_GATHER_SM5``: Whether the texture gather
210 hardware implements the SM5 features, component selection,
211 shadow comparison, and run-time offsets.
214 for buffers.
215 * ``PIPE_CAP_TEXTURE_QUERY_LOD``: Whether the ``LODQ`` instruction is
216 supported.
217 * ``PIPE_CAP_MIN_TEXTURE_GATHER_OFFSET``: The minimum offset that can be used
218 in conjunction with a texture gather opcode.
219 * ``PIPE_CAP_MAX_TEXTURE_GATHER_OFFSET``: The maximum offset that can be used
220 in conjunction with a texture gather opcode.
221 * ``PIPE_CAP_SAMPLE_SHADING``: Whether there is support for per-sample
222 shading. The context->set_min_samples function will be expected to be
223 implemented.
224 * ``PIPE_CAP_TEXTURE_GATHER_OFFSETS``: Whether the ``TG4`` instruction can
225 accept 4 offsets.
227 TGSI_PROPERTY_VS_WINDOW_SPACE_POSITION is supported, which disables clipping
228 and viewport transformation.
229 * ``PIPE_CAP_MAX_VERTEX_STREAMS``: The maximum number of vertex streams
230 supported by the geometry shader. If stream-out is supported, this should be
231 at least 1. If stream-out is not supported, this should be 0.
232 * ``PIPE_CAP_DRAW_INDIRECT``: Whether the driver supports taking draw arguments
233 { count, instance_count, start, index_bias } from a PIPE_BUFFER resource.
234 See pipe_draw_info.
235 * ``PIPE_CAP_MULTI_DRAW_INDIRECT``: Whether the driver supports
236 pipe_draw_info::indirect_stride and ::indirect_count
237 * ``PIPE_CAP_MULTI_DRAW_INDIRECT_PARAMS``: Whether the driver supports
238 taking the number of indirect draws from a separate parameter
239 buffer, see pipe_draw_indirect_info::indirect_draw_count.
240 * ``PIPE_CAP_TGSI_FS_FINE_DERIVATIVE``: Whether the fragment shader supports
241 the FINE versions of DDX/DDY.
242 * ``PIPE_CAP_VENDOR_ID``: The vendor ID of the underlying hardware. If it's
243 not available one should return 0xFFFFFFFF.
244 * ``PIPE_CAP_DEVICE_ID``: The device ID (PCI ID) of the underlying hardware.
245 0xFFFFFFFF if not available.
246 * ``PIPE_CAP_ACCELERATED``: Whether the renderer is hardware accelerated.
247 * ``PIPE_CAP_VIDEO_MEMORY``: The amount of video memory in megabytes.
248 * ``PIPE_CAP_UMA``: If the device has a unified memory architecture or on-card
249 memory and GART.
250 * ``PIPE_CAP_CONDITIONAL_RENDER_INVERTED``: Whether the driver supports inverted
251 condition for conditional rendering.
252 * ``PIPE_CAP_MAX_VERTEX_ATTRIB_STRIDE``: The maximum supported vertex stride.
253 * ``PIPE_CAP_SAMPLER_VIEW_TARGET``: Whether the sampler view's target can be
254 different than the underlying resource's, as permitted by
255 ARB_texture_view. For example a 2d array texture may be reinterpreted as a
256 cube (array) texture and vice-versa.
257 * ``PIPE_CAP_CLIP_HALFZ``: Whether the driver supports the
258 pipe_rasterizer_state::clip_halfz being set to true. This is required
259 for enabling ARB_clip_control.
260 * ``PIPE_CAP_VERTEXID_NOBASE``: If true, the driver only supports
262 gallium frontends for APIs whose vertexIDs are offset by basevertex (such as GL)
264 and TGSI_SEMANTIC_BASEVERTEX, so drivers setting this must handle both these
265 semantics. Only relevant if geometry shaders are supported.
266 (BASEVERTEX could be exposed separately too via ``PIPE_CAP_DRAW_PARAMETERS``).
267 * ``PIPE_CAP_POLYGON_OFFSET_CLAMP``: If true, the driver implements support
268 for ``pipe_rasterizer_state::offset_clamp``.
269 * ``PIPE_CAP_MULTISAMPLE_Z_RESOLVE``: Whether the driver supports blitting
270 a multisampled depth buffer into a single-sampled texture (or depth buffer).
271 Only the first sampled should be copied.
272 * ``PIPE_CAP_RESOURCE_FROM_USER_MEMORY``: Whether the driver can create
273 a pipe_resource where an already-existing piece of (malloc'd) user memory
274 is used as its backing storage. In other words, whether the driver can map
275 existing user memory into the device address space for direct device access.
276 The create function is pipe_screen::resource_from_user_memory. The address
277 and size must be page-aligned.
279 ``PIPE_CAP_RESOURCE_FROM_USER_MEMORY`` but indicates it is only supported from
280 the compute engines.
282 Whether pipe_context::get_device_reset_status is implemented.
284 How many per-patch outputs and inputs are supported between tessellation
285 control and tessellation evaluation shaders, not counting in TESSINNER and
286 TESSOUTER. The minimum allowed value for OpenGL is 30.
287 * ``PIPE_CAP_TEXTURE_FLOAT_LINEAR``: Whether the linear minification and
288 magnification filters are supported with single-precision floating-point
289 textures.
290 * ``PIPE_CAP_TEXTURE_HALF_FLOAT_LINEAR``: Whether the linear minification and
291 magnification filters are supported with half-precision floating-point
292 textures.
293 * ``PIPE_CAP_DEPTH_BOUNDS_TEST``: Whether bounds_test, bounds_min, and
294 bounds_max states of pipe_depth_stencil_alpha_state behave according
295 to the GL_EXT_depth_bounds_test specification.
296 * ``PIPE_CAP_TGSI_TXQS``: Whether the `TXQS` opcode is supported
297 * ``PIPE_CAP_FORCE_PERSAMPLE_INTERP``: If the driver can force per-sample
298 interpolation for all fragment shader inputs if
299 pipe_rasterizer_state::force_persample_interp is set. This is only used
300 by GL3-level sample shading (ARB_sample_shading). GL4-level sample shading
301 (ARB_gpu_shader5) doesn't use this. While GL3 hardware has a state for it,
302 GL4 hardware will likely need to emulate it with a shader variant, or by
303 selecting the interpolation weights with a conditional assignment
304 in the shader.
305 * ``PIPE_CAP_SHAREABLE_SHADERS``: Whether shader CSOs can be used by any
306 pipe_context.
308 Whether copying between compressed and plain formats is supported where
309 a compressed block is copied to/from a plain pixel of the same size.
310 * ``PIPE_CAP_CLEAR_TEXTURE``: Whether `clear_texture` will be
311 available in contexts.
312 * ``PIPE_CAP_CLEAR_SCISSORED``: Whether `clear` can accept a scissored
313 bounding box.
316 supported in vertex shaders.
317 * ``PIPE_CAP_TGSI_PACK_HALF_FLOAT``: Whether the ``UP2H`` and ``PK2H``
318 TGSI opcodes are supported.
319 * ``PIPE_CAP_TGSI_FS_POSITION_IS_SYSVAL``: If gallium frontends should use
320 a system value for the POSITION fragment shader input.
321 * ``PIPE_CAP_TGSI_FS_POINT_IS_SYSVAL``: If gallium frontends should use
322 a system value for the POINT fragment shader input.
323 * ``PIPE_CAP_TGSI_FS_FACE_IS_INTEGER_SYSVAL``: If gallium frontends should use
324 a system value for the FACE fragment shader input.
325 Also, the FACE system value is integer, not float.
326 * ``PIPE_CAP_SHADER_BUFFER_OFFSET_ALIGNMENT``: Describes the required
327 alignment for pipe_shader_buffer::buffer_offset, in bytes. Maximum
328 value allowed is 256 (for GL conformance). 0 is only allowed if
329 shader buffers are not supported.
330 * ``PIPE_CAP_INVALIDATE_BUFFER``: Whether the use of ``invalidate_resource``
331 for buffers is supported.
332 * ``PIPE_CAP_GENERATE_MIPMAP``: Indicates whether pipe_context::generate_mipmap
333 is supported.
334 * ``PIPE_CAP_STRING_MARKER``: Whether pipe->emit_string_marker() is supported.
335 * ``PIPE_CAP_SURFACE_REINTERPRET_BLOCKS``: Indicates whether
336 pipe_context::create_surface supports reinterpreting a texture as a surface
337 of a format with different block width/height (but same block size in bits).
338 For example, a compressed texture image can be interpreted as a
339 non-compressed surface whose texels are the same number of bits as the
340 compressed blocks, and vice versa. The width and height of the surface is
341 adjusted appropriately.
342 * ``PIPE_CAP_QUERY_BUFFER_OBJECT``: Driver supports
343 context::get_query_result_resource callback.
344 * ``PIPE_CAP_PCI_GROUP``: Return the PCI segment group number.
345 * ``PIPE_CAP_PCI_BUS``: Return the PCI bus number.
346 * ``PIPE_CAP_PCI_DEVICE``: Return the PCI device number.
347 * ``PIPE_CAP_PCI_FUNCTION``: Return the PCI function number.
349 If non-zero, rendering to framebuffers with no surface attachments
350 is supported. The context->is_format_supported function will be expected
351 to be implemented with PIPE_FORMAT_NONE yeilding the MSAA modes the hardware
352 supports. N.B., The maximum number of layers supported for rasterizing a
353 primitive on a layer is obtained from ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS``
354 even though it can be larger than the number of layers supported by either
355 rendering or textures.
356 * ``PIPE_CAP_ROBUST_BUFFER_ACCESS_BEHAVIOR``: Implementation uses bounds
357 checking on resource accesses by shader if the context is created with
358 PIPE_CONTEXT_ROBUST_BUFFER_ACCESS. See the ARB_robust_buffer_access_behavior
359 extension for information on the required behavior for out of bounds accesses
360 and accesses to unbound resources.
361 * ``PIPE_CAP_CULL_DISTANCE``: Whether the driver supports the arb_cull_distance
362 extension and thus implements proper support for culling planes.
363 * ``PIPE_CAP_PRIMITIVE_RESTART_FOR_PATCHES``: Whether primitive restart is
364 supported for patch primitives.
365 * ``PIPE_CAP_TGSI_VOTE``: Whether the ``VOTE_*`` ops can be used in shaders.
366 * ``PIPE_CAP_MAX_WINDOW_RECTANGLES``: The maxium number of window rectangles
367 supported in ``set_window_rectangles``.
368 * ``PIPE_CAP_POLYGON_OFFSET_UNITS_UNSCALED``: If true, the driver implements support
369 for ``pipe_rasterizer_state::offset_units_unscaled``.
370 * ``PIPE_CAP_VIEWPORT_SUBPIXEL_BITS``: Number of bits of subpixel precision for
371 floating point viewport bounds.
372 * ``PIPE_CAP_RASTERIZER_SUBPIXEL_BITS``: Number of bits of subpixel precision used
373 by the rasterizer.
374 * ``PIPE_CAP_MIXED_COLOR_DEPTH_BITS``: Whether there is non-fallback
375 support for color/depth format combinations that use a different
376 number of bits. For the purpose of this cap, Z24 is treated as
377 32-bit. If set to off, that means that a B5G6R5 + Z24 or RGBA8 + Z16
378 combination will require a driver fallback, and should not be
379 advertised in the GLX/EGL config list.
380 * ``PIPE_CAP_TGSI_ARRAY_COMPONENTS``: If true, the driver interprets the
381 UsageMask of input and output declarations and allows declaring arrays
382 in overlapping ranges. The components must be a contiguous range, e.g. a
383 UsageMask of xy or yzw is allowed, but xz or yw isn't. Declarations with
384 overlapping locations must have matching semantic names and indices, and
385 equal interpolation qualifiers.
386 Components may overlap, notably when the gaps in an array of dvec3 are
387 filled in.
388 * ``PIPE_CAP_STREAM_OUTPUT_INTERLEAVE_BUFFERS``: Whether interleaved stream
389 output mode is able to interleave across buffers. This is required for
390 ARB_transform_feedback3.
391 * ``PIPE_CAP_TGSI_CAN_READ_OUTPUTS``: Whether every TGSI shader stage can read
392 from the output file.
393 * ``PIPE_CAP_GLSL_OPTIMIZE_CONSERVATIVELY``: Tell the GLSL compiler to use
394 the minimum amount of optimizations just to be able to do all the linking
395 and lowering.
396 * ``PIPE_CAP_FBFETCH``: The number of render targets whose value in the
397 current framebuffer can be read in the shader. 0 means framebuffer fetch
398 is not supported. 1 means that only the first render target can be read,
399 and a larger value would mean that multiple render targets are supported.
400 * ``PIPE_CAP_FBFETCH_COHERENT``: Whether framebuffer fetches from the fragment
401 shader can be guaranteed to be coherent with framebuffer writes.
402 * ``PIPE_CAP_TGSI_MUL_ZERO_WINS``: Whether TGSI shaders support the
403 ``TGSI_PROPERTY_MUL_ZERO_WINS`` shader property.
404 * ``PIPE_CAP_DOUBLES``: Whether double precision floating-point operations
405 are supported.
406 * ``PIPE_CAP_INT64``: Whether 64-bit integer operations are supported.
407 * ``PIPE_CAP_INT64_DIVMOD``: Whether 64-bit integer division/modulo
408 operations are supported.
409 * ``PIPE_CAP_TGSI_TEX_TXF_LZ``: Whether TEX_LZ and TXF_LZ opcodes are
410 supported.
411 * ``PIPE_CAP_TGSI_CLOCK``: Whether the CLOCK opcode is supported.
413 PIPE_POLYGON_MODE_FILL_RECTANGLE mode is supported for
414 ``pipe_rasterizer_state::fill_front`` and
415 ``pipe_rasterizer_state::fill_back``.
416 * ``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``: The page size of sparse buffers in
417 bytes, or 0 if sparse buffers are not supported. The page size must be at
418 most 64KB.
419 * ``PIPE_CAP_TGSI_BALLOT``: Whether the BALLOT and READ_* opcodes as well as
420 the SUBGROUP_* semantics are supported.
422 ``TGSI_SEMANTIC_VIEWPORT_INDEX`` are supported as tessellation evaluation
423 shader outputs.
424 * ``PIPE_CAP_CAN_BIND_CONST_BUFFER_AS_VERTEX``: Whether a buffer with just
425 PIPE_BIND_CONSTANT_BUFFER can be legally passed to set_vertex_buffers.
429 * ``PIPE_CAP_BINDLESS_TEXTURE``: Whether bindless texture operations are
430 supported.
431 * ``PIPE_CAP_NIR_SAMPLERS_AS_DEREF``: Whether NIR tex instructions should
432 reference texture and sampler as NIR derefs instead of by indices.
433 * ``PIPE_CAP_QUERY_SO_OVERFLOW``: Whether the
435 ``PIPE_QUERY_SO_OVERFLOW_ANY_PREDICATE`` query types are supported. Note that
436 for a driver that does not support multiple output streams (i.e.,
437 ``PIPE_CAP_MAX_VERTEX_STREAMS`` is 1), both query types are identical.
438 * ``PIPE_CAP_MEMOBJ``: Whether operations on memory objects are supported.
439 * ``PIPE_CAP_LOAD_CONSTBUF``: True if the driver supports ``TGSI_OPCODE_LOAD`` use
440 with constant buffers.
441 * ``PIPE_CAP_TGSI_ANY_REG_AS_ADDRESS``: Any TGSI register can be used as
442 an address for indirect register indexing.
443 * ``PIPE_CAP_TILE_RASTER_ORDER``: Whether the driver supports
444 GL_MESA_tile_raster_order, using the tile_raster_order_* fields in
445 pipe_rasterizer_state.
446 * ``PIPE_CAP_MAX_COMBINED_SHADER_OUTPUT_RESOURCES``: Limit on combined shader
447 output resources (images + buffers + fragment outputs). If 0 the state
448 tracker works it out.
449 * ``PIPE_CAP_FRAMEBUFFER_MSAA_CONSTRAINTS``: This determines limitations
450 on the number of samples that framebuffer attachments can have.
451 Possible values:
453 0. color.nr_samples == zs.nr_samples == color.nr_storage_samples
454 (standard MSAA quality)
455 1. color.nr_samples >= zs.nr_samples == color.nr_storage_samples
456 (enhanced MSAA quality)
457 2. color.nr_samples >= zs.nr_samples >= color.nr_storage_samples
458 (full flexibility in tuning MSAA quality and performance)
460 All color attachments must have the same number of samples and the same
461 number of storage samples.
463 Whether pipe_vertex_buffer::buffer_offset is treated as signed. The u_vbuf
464 module needs this for optimal performance in workstation applications.
465 * ``PIPE_CAP_CONTEXT_PRIORITY_MASK``: For drivers that support per-context
466 priorities, this returns a bitmask of ``PIPE_CONTEXT_PRIORITY_x`` for the
467 supported priority levels. A driver that does not support prioritized
468 contexts can return 0.
469 * ``PIPE_CAP_FENCE_SIGNAL``: True if the driver supports signaling semaphores
470 using fence_server_signal().
471 * ``PIPE_CAP_CONSTBUF0_FLAGS``: The bits of pipe_resource::flags that must be
472 set when binding that buffer as constant buffer 0. If the buffer doesn't have
473 those bits set, pipe_context::set_constant_buffer(.., 0, ..) is ignored
474 by the driver, and the driver can throw assertion failures.
475 * ``PIPE_CAP_PACKED_UNIFORMS``: True if the driver supports packed uniforms
476 as opposed to padding to vec4s.
478 ``PIPE_CONSERVATIVE_RASTER_POST_SNAP`` mode is supported for triangles.
479 The post-snap mode means the conservative rasterization occurs after
480 the conversion from floating-point to fixed-point coordinates
481 on the subpixel grid.
483 ``PIPE_CONSERVATIVE_RASTER_POST_SNAP`` mode is supported for points and lines.
485 ``PIPE_CONSERVATIVE_RASTER_PRE_SNAP`` mode is supported for triangles.
486 The pre-snap mode means the conservative rasterization occurs before
487 the conversion from floating-point to fixed-point coordinates.
489 ``PIPE_CONSERVATIVE_RASTER_PRE_SNAP`` mode is supported for points and lines.
491 ``PIPE_CAP_POST_DEPTH_COVERAGE`` works with conservative rasterization.
493 inner_coverage from GL_INTEL_conservative_rasterization is supported.
495 subpixel precision bias in bits during conservative rasterization.
496 * ``PIPE_CAP_PROGRAMMABLE_SAMPLE_LOCATIONS``: True is the driver supports
497 programmable sample location through ```get_sample_pixel_grid``` and
498 ```set_sample_locations```.
499 * ``PIPE_CAP_MAX_GS_INVOCATIONS``: Maximum supported value of
501 * ``PIPE_CAP_MAX_SHADER_BUFFER_SIZE``: Maximum supported size for binding
502 with set_shader_buffers.
503 * ``PIPE_CAP_MAX_COMBINED_SHADER_BUFFERS``: Maximum total number of shader
504 buffers. A value of 0 means the sum of all per-shader stage maximums (see
506 * ``PIPE_CAP_MAX_COMBINED_HW_ATOMIC_COUNTERS``: Maximum total number of atomic
507 counters. A value of 0 means the default value (MAX_ATOMIC_COUNTERS = 4096).
508 * ``PIPE_CAP_MAX_COMBINED_HW_ATOMIC_COUNTER_BUFFERS``: Maximum total number of
509 atomic counter buffers. A value of 0 means the sum of all per-shader stage
511 * ``PIPE_CAP_MAX_TEXTURE_UPLOAD_MEMORY_BUDGET``: Maximum recommend memory size
512 for all active texture uploads combined. This is a performance hint.
513 0 means no limit.
514 * ``PIPE_CAP_MAX_VERTEX_ELEMENT_SRC_OFFSET``: The maximum supported value for
515 of pipe_vertex_element::src_offset.
516 * ``PIPE_CAP_SURFACE_SAMPLE_COUNT``: Whether the driver
517 supports pipe_surface overrides of resource nr_samples. If set, will
518 enable EXT_multisampled_render_to_texture.
519 * ``PIPE_CAP_TGSI_ATOMFADD``: Atomic floating point adds are supported on
520 images, buffers, and shared memory.
521 * ``PIPE_CAP_RGB_OVERRIDE_DST_ALPHA_BLEND``: True if the driver needs blend state to use zero/one instead of destination alpha for RGB/XRGB formats.
522 * ``PIPE_CAP_GLSL_TESS_LEVELS_AS_INPUTS``: True if the driver wants TESSINNER and TESSOUTER to be inputs (rather than system values) for tessellation evaluation shaders.
523 * ``PIPE_CAP_DEST_SURFACE_SRGB_CONTROL``: Indicates whether the drivers
524 supports switching the format between sRGB and linear for a surface that is
525 used as destination in draw and blit calls.
526 * ``PIPE_CAP_NIR_COMPACT_ARRAYS``: True if the compiler backend supports NIR's compact array feature, for all shader stages.
527 * ``PIPE_CAP_MAX_VARYINGS``: The maximum number of fragment shader
528 varyings. This will generally correspond to
529 ``PIPE_SHADER_CAP_MAX_INPUTS`` for the fragment shader, but in some
530 cases may be a smaller number.
531 * ``PIPE_CAP_COMPUTE_GRID_INFO_LAST_BLOCK``: Whether pipe_grid_info::last_block
532 is implemented by the driver. See struct pipe_grid_info for more details.
533 * ``PIPE_CAP_COMPUTE_SHADER_DERIVATIVE``: True if the driver supports derivatives (and texture lookups with implicit derivatives) in compute shaders.
534 * ``PIPE_CAP_TGSI_SKIP_SHRINK_IO_ARRAYS``: Whether the TGSI pass to shrink IO
535 arrays should be skipped and enforce keeping the declared array sizes instead.
536 A driver might rely on the input mapping that was defined with the original
537 GLSL code.
538 * ``PIPE_CAP_IMAGE_LOAD_FORMATTED``: True if a format for image loads does not need to be specified in the shader IR
539 * ``PIPE_CAP_THROTTLE``: Whether or not gallium frontends should throttle pipe_context
540 execution. 0 = throttling is disabled.
541 * ``PIPE_CAP_DMABUF``: Whether Linux DMABUF handles are supported by
542 resource_from_handle and resource_get_handle.
544 OpenMAX should use a compute-based blit instead of pipe_context::blit and compute pipeline for compositing images.
545 * ``PIPE_CAP_FRAGMENT_SHADER_INTERLOCK``: True if fragment shader interlock
546 functionality is supported.
547 * ``PIPE_CAP_CS_DERIVED_SYSTEM_VALUES_SUPPORTED``: True if driver handles
548 gl_LocalInvocationIndex and gl_GlobalInvocationID. Otherwise, gallium frontends will
549 lower those system values.
550 * ``PIPE_CAP_ATOMIC_FLOAT_MINMAX``: Atomic float point minimum,
551 maximum, exchange and compare-and-swap support to buffer and shared variables.
552 * ``PIPE_CAP_TGSI_DIV``: Whether opcode DIV is supported
553 * ``PIPE_CAP_FRAGMENT_SHADER_TEXTURE_LOD``: Whether texture lookups with
554 explicit LOD is supported in the fragment shader.
555 * ``PIPE_CAP_FRAGMENT_SHADER_DERIVATIVES``: True if the driver supports
556 derivatives in fragment shaders.
557 * ``PIPE_CAP_VERTEX_SHADER_SATURATE``: True if the driver supports saturate
558 modifiers in the vertex shader.
559 * ``PIPE_CAP_TEXTURE_SHADOW_LOD``: True if the driver supports shadow sampler
560 types with texture functions having interaction with LOD of texture lookup.
561 * ``PIPE_CAP_SHADER_SAMPLES_IDENTICAL``: True if the driver supports a shader query to tell whether all samples of a multisampled surface are definitely identical.
562 * ``PIPE_CAP_TGSI_ATOMINC_WRAP``: Atomic increment/decrement + wrap around are supported.
563 * ``PIPE_CAP_PREFER_IMM_ARRAYS_AS_CONSTBUF``: True if gallium frontends should
564 turn arrays whose contents can be deduced at compile time into constant
565 buffer loads, or false if the driver can handle such arrays itself in a more
566 efficient manner.
567 * ``PIPE_CAP_GL_SPIRV``: True if the driver supports ARB_gl_spirv extension.
568 * ``PIPE_CAP_GL_SPIRV_VARIABLE_POINTERS``: True if the driver supports Variable Pointers in SPIR-V shaders.
569 * ``PIPE_CAP_DEMOTE_TO_HELPER_INVOCATION``: True if driver supports demote keyword in GLSL programs.
570 * ``PIPE_CAP_TGSI_TG4_COMPONENT_IN_SWIZZLE``: True if driver wants the TG4 component encoded in sampler swizzle rather than as a separate source.
571 * ``PIPE_CAP_FLATSHADE``: Driver supports pipe_rasterizer_state::flatshade.
572 * ``PIPE_CAP_ALPHA_TEST``: Driver supports alpha-testing.
573 * ``PIPE_CAP_POINT_SIZE_FIXED``: Driver supports point-sizes that are fixed,
574 as opposed to writing gl_PointSize for every point.
575 * ``PIPE_CAP_TWO_SIDED_COLOR``: Driver supports two-sided coloring.
576 * ``PIPE_CAP_CLIP_PLANES``: Driver supports user-defined clip-planes.
577 * ``PIPE_CAP_MAX_VERTEX_BUFFERS``: Number of supported vertex buffers.
578 * ``PIPE_CAP_OPENCL_INTEGER_FUNCTIONS``: Driver supports extended OpenCL-style integer functions. This includes averge, saturating additiong, saturating subtraction, absolute difference, count leading zeros, and count trailing zeros.
579 * ``PIPE_CAP_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.
580 * ``PIPE_CAP_NIR_IMAGES_AS_DEREF``: Whether NIR image load/store intrinsics should be nir_intrinsic_image_deref_* instead of nir_intrinsic_image_*. Defaults to true.
581 * ``PIPE_CAP_PACKED_STREAM_OUTPUT``: Driver supports packing optimization for stream output (e.g. GL transform feedback captured variables). Defaults to true.
582 * ``PIPE_CAP_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.
583 * ``PIPE_CAP_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.
584 * ``PIPE_CAP_DRAW_INFO_START_WITH_USER_INDICES``: pipe_draw_info::start can be non-zero with user indices.
585 * ``PIPE_CAP_GL_BEGIN_END_BUFFER_SIZE``: Buffer size used to upload vertices for glBegin/glEnd.
586 * ``PIPE_CAP_VIEWPORT_SWIZZLE``: Whether pipe_viewport_state::swizzle can be used to specify pre-clipping swizzling of coordinates (see GL_NV_viewport_swizzle).
587 * ``PIPE_CAP_SYSTEM_SVM``: True if all application memory can be shared with the GPU without explicit mapping.
588 * ``PIPE_CAP_VIEWPORT_MASK``: Whether ``TGSI_SEMANTIC_VIEWPORT_MASK`` and ``TGSI_PROPERTY_LAYER_VIEWPORT_RELATIVE`` are supported (see GL_NV_viewport_array2).
589 * ``PIPE_CAP_MAP_UNSYNCHRONIZED_THREAD_SAFE``: Whether mapping a buffer as unsynchronized from any thread is safe.
590 * ``PIPE_CAP_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.
592 .. _pipe_capf:
595 ^^^^^^^^^^^^^^^^
597 The floating-point capabilities are:
599 * ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line.
600 * ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
601 * ``PIPE_CAPF_MAX_POINT_WIDTH``: The maximum width and height of a point.
602 * ``PIPE_CAPF_MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
603 * ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
604 applied to anisotropically filtered textures.
605 * ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
606 to filtered textures.
607 * ``PIPE_CAPF_MIN_CONSERVATIVE_RASTER_DILATE``: The minimum conservative rasterization
608 dilation.
609 * ``PIPE_CAPF_MAX_CONSERVATIVE_RASTER_DILATE``: The maximum conservative rasterization
610 dilation.
611 * ``PIPE_CAPF_CONSERVATIVE_RASTER_DILATE_GRANULARITY``: The conservative rasterization
612 dilation granularity for values relative to the minimum dilation.
615 .. _pipe_shader_cap:
618 ^^^^^^^^^^^^^^^^^
620 These are per-shader-stage capabitity queries. Different shader stages may
621 support different features.
623 * ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions.
624 * ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
625 * ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
626 * ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections.
627 * ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
628 * ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers.
629 * ``PIPE_SHADER_CAP_MAX_OUTPUTS``: The maximum number of output registers.
630 This is valid for all shaders except the fragment shader.
631 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFER_SIZE``: The maximum size per constant buffer in bytes.
632 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
633 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
634 only permit binding one constant buffer per shader.
636 If a value greater than 0 is returned, the driver can have multiple
637 constant buffers bound to shader stages. The CONST register file is
638 accessed with two-dimensional indices, like in the example below.
640 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
641 DCL CONST[3][0] # declare first vector of constbuf 3
642 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
644 * ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers.
645 * ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported.
646 * ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing
647 of the input file is supported.
648 * ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing
649 of the output file is supported.
650 * ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing
651 of the temporary file is supported.
652 * ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing
653 of the constant file is supported.
654 * ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e.
655 BGNSUB, ENDSUB, CAL, and RET, including RET in the main block.
656 * ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported.
657 If unsupported, only float opcodes are supported.
658 * ``PIPE_SHADER_CAP_INT64_ATOMICS``: Whether int64 atomic opcodes are supported. The device needs to support add, sub, swap, cmpswap, and, or, xor, min, and max.
659 * ``PIPE_SHADER_CAP_FP16``: Whether half precision floating-point opcodes are supported.
660 If unsupported, half precision ops need to be lowered to full precision.
661 * ``PIPE_SHADER_CAP_FP16_DERIVATIVES``: Whether half precision floating-point
662 DDX and DDY opcodes are supported.
663 * ``PIPE_SHADER_CAP_INT16``: Whether 16-bit signed and unsigned integer types
664 are supported.
665 * ``PIPE_SHADER_CAP_GLSL_16BIT_TEMPS``: Lower mediump temporaries to 16-bit.
666 This generates 16-bit phis in NIR, 16-bit loop counters, and 16-bit indirect arrays.
667 * ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: The maximum number of texture
668 samplers.
669 * ``PIPE_SHADER_CAP_PREFERRED_IR``: Preferred representation of the
670 program. It should be one of the ``pipe_shader_ir`` enum values.
671 * ``PIPE_SHADER_CAP_MAX_SAMPLER_VIEWS``: The maximum number of texture
672 sampler views. Must not be lower than PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS.
673 * ``PIPE_SHADER_CAP_TGSI_DROUND_SUPPORTED``: Whether double precision rounding
674 is supported. If it is, DTRUNC/DCEIL/DFLR/DROUND opcodes may be used.
676 DLDEXP are supported.
677 * ``PIPE_SHADER_CAP_TGSI_LDEXP_SUPPORTED``: Whether LDEXP is supported.
678 * ``PIPE_SHADER_CAP_TGSI_FMA_SUPPORTED``: Whether FMA and DFMA (doubles only)
679 are supported.
680 * ``PIPE_SHADER_CAP_TGSI_ANY_INOUT_DECL_RANGE``: Whether the driver doesn't
681 ignore tgsi_declaration_range::Last for shader inputs and outputs.
682 * ``PIPE_SHADER_CAP_MAX_UNROLL_ITERATIONS_HINT``: This is the maximum number
683 of iterations that loops are allowed to have to be unrolled. It is only
684 a hint to gallium frontends. Whether any loops will be unrolled is not
685 guaranteed.
686 * ``PIPE_SHADER_CAP_MAX_SHADER_BUFFERS``: Maximum number of memory buffers
687 (also used to implement atomic counters). Having this be non-0 also
688 implies support for the ``LOAD``, ``STORE``, and ``ATOM*`` TGSI
689 opcodes.
690 * ``PIPE_SHADER_CAP_SUPPORTED_IRS``: Supported representations of the
691 program. It should be a mask of ``pipe_shader_ir`` bits.
692 * ``PIPE_SHADER_CAP_MAX_SHADER_IMAGES``: Maximum number of image units.
693 * ``PIPE_SHADER_CAP_LOWER_IF_THRESHOLD``: IF and ELSE branches with a lower
694 cost than this value should be lowered by gallium frontends for better
695 performance. This is a tunable for the GLSL compiler and the behavior is
696 specific to the compiler.
697 * ``PIPE_SHADER_CAP_TGSI_SKIP_MERGE_REGISTERS``: Whether the merge registers
698 TGSI pass is skipped. This might reduce code size and register pressure if
699 the underlying driver has a real backend compiler.
700 * ``PIPE_SHADER_CAP_MAX_HW_ATOMIC_COUNTERS``: If atomic counters are separate,
701 how many HW counters are available for this stage. (0 uses SSBO atomics).
702 * ``PIPE_SHADER_CAP_MAX_HW_ATOMIC_COUNTER_BUFFERS``: If atomic counters are
703 separate, how many atomic counter buffers are available for this stage.
705 .. _pipe_compute_cap:
708 ^^^^^^^^^^^^^^^^^^
710 Compute-specific capabilities. They can be queried using
711 pipe_screen::get_compute_param.
713 * ``PIPE_COMPUTE_CAP_IR_TARGET``: A description of the target of the form
714 ``processor-arch-manufacturer-os`` that will be passed on to the compiler.
715 This CAP is only relevant for drivers that specify PIPE_SHADER_IR_NATIVE for
716 their preferred IR.
717 Value type: null-terminated string. Shader IR type dependent.
718 * ``PIPE_COMPUTE_CAP_GRID_DIMENSION``: Number of supported dimensions
719 for grid and block coordinates. Value type: ``uint64_t``. Shader IR type dependent.
720 * ``PIPE_COMPUTE_CAP_MAX_GRID_SIZE``: Maximum grid size in block
721 units. Value type: ``uint64_t []``. Shader IR type dependent.
722 * ``PIPE_COMPUTE_CAP_MAX_BLOCK_SIZE``: Maximum block size in thread
723 units. Value type: ``uint64_t []``. Shader IR type dependent.
724 * ``PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK``: Maximum number of threads that
725 a single block can contain. Value type: ``uint64_t``. Shader IR type dependent.
726 This may be less than the product of the components of MAX_BLOCK_SIZE and is
727 usually limited by the number of threads that can be resident simultaneously
728 on a compute unit.
729 * ``PIPE_COMPUTE_CAP_MAX_GLOBAL_SIZE``: Maximum size of the GLOBAL
730 resource. Value type: ``uint64_t``. Shader IR type dependent.
731 * ``PIPE_COMPUTE_CAP_MAX_LOCAL_SIZE``: Maximum size of the LOCAL
732 resource. Value type: ``uint64_t``. Shader IR type dependent.
733 * ``PIPE_COMPUTE_CAP_MAX_PRIVATE_SIZE``: Maximum size of the PRIVATE
734 resource. Value type: ``uint64_t``. Shader IR type dependent.
735 * ``PIPE_COMPUTE_CAP_MAX_INPUT_SIZE``: Maximum size of the INPUT
736 resource. Value type: ``uint64_t``. Shader IR type dependent.
737 * ``PIPE_COMPUTE_CAP_MAX_MEM_ALLOC_SIZE``: Maximum size of a memory object
738 allocation in bytes. Value type: ``uint64_t``.
739 * ``PIPE_COMPUTE_CAP_MAX_CLOCK_FREQUENCY``: Maximum frequency of the GPU
740 clock in MHz. Value type: ``uint32_t``
741 * ``PIPE_COMPUTE_CAP_MAX_COMPUTE_UNITS``: Maximum number of compute units
742 Value type: ``uint32_t``
743 * ``PIPE_COMPUTE_CAP_IMAGES_SUPPORTED``: Whether images are supported
744 non-zero means yes, zero means no. Value type: ``uint32_t``
745 * ``PIPE_COMPUTE_CAP_SUBGROUP_SIZE``: The size of a basic execution unit in
746 threads. Also known as wavefront size, warp size or SIMD width.
747 * ``PIPE_COMPUTE_CAP_ADDRESS_BITS``: The default compute device address space
748 size specified as an unsigned integer value in bits.
749 * ``PIPE_COMPUTE_CAP_MAX_VARIABLE_THREADS_PER_BLOCK``: Maximum variable number
750 of threads that a single block can contain. This is similar to
751 PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK, except that the variable size is not
752 known a compile-time but at dispatch-time.
754 .. _pipe_bind:
757 ^^^^^^^^^^^
759 These flags indicate how a resource will be used and are specified at resource
760 creation time. Resources may be used in different roles
761 during their lifecycle. Bind flags are cumulative and may be combined to create
762 a resource which can be used for multiple things.
763 Depending on the pipe driver's memory management and these bind flags,
764 resources might be created and handled quite differently.
766 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
767 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs
768 must have this flag set.
769 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
770 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
771 have this flag set.
772 * ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to
773 query whether a device supports blending for a given format.
774 If this flag is set, surface creation may fail if blending is not supported
775 for the specified format. If it is not set, a driver may choose to ignore
776 blending on surfaces with formats that would require emulation.
777 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
778 pipe_screen::flush_front_buffer must have this flag set.
779 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
780 or vertex shader.
781 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
782 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
783 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
784 * ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer.
786 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
787 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
788 process.
789 * ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global
790 address space of a compute program.
791 * ``PIPE_BIND_SHADER_BUFFER``: A buffer without a format that can be bound
792 to a shader and can be used with load, store, and atomic instructions.
793 * ``PIPE_BIND_SHADER_IMAGE``: A buffer or texture with a format that can be
794 bound to a shader and can be used with load, store, and atomic instructions.
795 * ``PIPE_BIND_COMPUTE_RESOURCE``: A buffer or texture that can be
796 bound to the compute program as a shader resource.
797 * ``PIPE_BIND_COMMAND_ARGS_BUFFER``: A buffer that may be sourced by the
798 GPU command processor. It can contain, for example, the arguments to
799 indirect draw calls.
801 .. _pipe_usage:
804 ^^^^^^^^^^^^
806 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
807 Note that drivers must always support read and write CPU access at any time
808 no matter which hint they got.
810 * ``PIPE_USAGE_DEFAULT``: Optimized for fast GPU access.
811 * ``PIPE_USAGE_IMMUTABLE``: Optimized for fast GPU access and the resource is
812 not expected to be mapped or changed (even by the GPU) after the first upload.
813 * ``PIPE_USAGE_DYNAMIC``: Expect frequent write-only CPU access. What is
814 uploaded is expected to be used at least several times by the GPU.
815 * ``PIPE_USAGE_STREAM``: Expect frequent write-only CPU access. What is
816 uploaded is expected to be used only once by the GPU.
817 * ``PIPE_USAGE_STAGING``: Optimized for fast CPU access.
820 Methods
821 -------
823 XXX to-do
825 get_name
826 ^^^^^^^^
828 Returns an identifying name for the screen.
830 The returned string should remain valid and immutable for the lifetime of
831 pipe_screen.
833 get_vendor
834 ^^^^^^^^^^
836 Returns the screen vendor.
838 The returned string should remain valid and immutable for the lifetime of
839 pipe_screen.
841 get_device_vendor
842 ^^^^^^^^^^^^^^^^^
844 Returns the actual vendor of the device driving the screen
845 (as opposed to the driver vendor).
847 The returned string should remain valid and immutable for the lifetime of
848 pipe_screen.
850 .. _get_param:
852 get_param
853 ^^^^^^^^^
855 Get an integer/boolean screen parameter.
857 **param** is one of the :ref:`PIPE_CAP` names.
859 .. _get_paramf:
861 get_paramf
862 ^^^^^^^^^^
864 Get a floating-point screen parameter.
866 **param** is one of the :ref:`PIPE_CAPF` names.
868 context_create
869 ^^^^^^^^^^^^^^
871 Create a pipe_context.
873 **priv** is private data of the caller, which may be put to various
874 unspecified uses, typically to do with implementing swapbuffers
875 and/or front-buffer rendering.
877 is_format_supported
878 ^^^^^^^^^^^^^^^^^^^
880 Determine if a resource in the given format can be used in a specific manner.
882 **format** the resource format
884 **target** one of the PIPE_TEXTURE_x flags
886 **sample_count** the number of samples. 0 and 1 mean no multisampling,
887 the maximum allowed legal value is 32.
889 **storage_sample_count** the number of storage samples. This must be <=
890 sample_count. See the documentation of ``pipe_resource::nr_storage_samples``.
892 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
894 Returns TRUE if all usages can be satisfied.
897 can_create_resource
898 ^^^^^^^^^^^^^^^^^^^
900 Check if a resource can actually be created (but don't actually allocate any
901 memory). This is used to implement OpenGL's proxy textures. Typically, a
902 driver will simply check if the total size of the given resource is less than
903 some limit.
905 For PIPE_TEXTURE_CUBE, the pipe_resource::array_size field should be 6.
908 .. _resource_create:
910 resource_create
911 ^^^^^^^^^^^^^^^
913 Create a new resource from a template.
914 The following fields of the pipe_resource must be specified in the template:
916 **target** one of the pipe_texture_target enums.
917 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
918 Modern APIs allow using buffers as shader resources.
920 **format** one of the pipe_format enums.
922 **width0** the width of the base mip level of the texture or size of the buffer.
924 **height0** the height of the base mip level of the texture
925 (1 for 1D or 1D array textures).
927 **depth0** the depth of the base mip level of the texture
928 (1 for everything else).
930 **array_size** the array size for 1D and 2D array textures.
931 For cube maps this must be 6, for other textures 1.
933 **last_level** the last mip map level present.
935 **nr_samples**: Number of samples determining quality, driving the rasterizer,
936 shading, and framebuffer. It is the number of samples seen by the whole
937 graphics pipeline. 0 and 1 specify a resource which isn't multisampled.
939 **nr_storage_samples**: Only color buffers can set this lower than nr_samples.
940 Multiple samples within a pixel can have the same color. ``nr_storage_samples``
941 determines how many slots for different colors there are per pixel.
942 If there are not enough slots to store all sample colors, some samples will
943 have an undefined color (called "undefined samples").
945 The resolve blit behavior is driver-specific, but can be one of these two:
947 1. Only defined samples will be averaged. Undefined samples will be ignored.
948 2. Undefined samples will be approximated by looking at surrounding defined
949 samples (even in different pixels).
951 Blits and MSAA texturing: If the sample being fetched is undefined, one of
952 the defined samples is returned instead.
954 Sample shading (``set_min_samples``) will operate at a sample frequency that
955 is at most ``nr_storage_samples``. Greater ``min_samples`` values will be
956 replaced by ``nr_storage_samples``.
958 **usage** one of the :ref:`PIPE_USAGE` flags.
960 **bind** bitmask of the :ref:`PIPE_BIND` flags.
962 **flags** bitmask of PIPE_RESOURCE_FLAG flags.
964 **next**: Pointer to the next plane for resources that consist of multiple
965 memory planes.
967 As a corollary, this mean resources for an image with multiple planes have
968 to be created starting from the highest plane.
970 resource_changed
971 ^^^^^^^^^^^^^^^^
973 Mark a resource as changed so derived internal resources will be recreated
974 on next use.
976 When importing external images that can't be directly used as texture sampler
977 source, internal copies may have to be created that the hardware can sample
978 from. When those resources are reimported, the image data may have changed, and
979 the previously derived internal resources must be invalidated to avoid sampling
980 from old copies.
984 resource_destroy
985 ^^^^^^^^^^^^^^^^
987 Destroy a resource. A resource is destroyed if it has no more references.
991 get_timestamp
992 ^^^^^^^^^^^^^
994 Query a timestamp in nanoseconds. The returned value should match
995 PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't
996 wait for rendering to complete (which cannot be achieved with queries).
1000 get_driver_query_info
1001 ^^^^^^^^^^^^^^^^^^^^^
1003 Return a driver-specific query. If the **info** parameter is NULL,
1004 the number of available queries is returned. Otherwise, the driver
1005 query at the specified **index** is returned in **info**.
1006 The function returns non-zero on success.
1007 The driver-specific query is described with the pipe_driver_query_info
1008 structure.
1010 get_driver_query_group_info
1011 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1013 Return a driver-specific query group. If the **info** parameter is NULL,
1014 the number of available groups is returned. Otherwise, the driver
1015 query group at the specified **index** is returned in **info**.
1016 The function returns non-zero on success.
1017 The driver-specific query group is described with the
1018 pipe_driver_query_group_info structure.
1022 get_disk_shader_cache
1023 ^^^^^^^^^^^^^^^^^^^^^
1025 Returns a pointer to a driver-specific on-disk shader cache. If the driver
1026 failed to create the cache or does not support an on-disk shader cache NULL is
1027 returned. The callback itself may also be NULL if the driver doesn't support
1028 an on-disk shader cache.
1031 Thread safety
1032 -------------
1034 Screen methods are required to be thread safe. While gallium rendering
1035 contexts are not required to be thread safe, it is required to be safe to use
1036 different contexts created with the same screen in different threads without
1037 locks. It is also required to be safe using screen methods in a thread, while
1038 using one of its contexts in another (without locks).