6
A screen is an object representing the context-independent part of a device.
11
XXX some of these don't belong in this section.
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
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
40
* ``PIPE_CAP_TEXTURE_SWIZZLE``: Whether swizzling through sampler views is
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
45
* ``PIPE_CAP_MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
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.
55
* ``PIPE_CAP_PRIMITIVE_RESTART_FIXED_INDEX``: Subset of
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
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_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the upper-left origin
68
fragment convention is supported.
69
* ``PIPE_CAP_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the lower-left origin
70
fragment convention is supported.
71
* ``PIPE_CAP_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the half-integer
72
pixel-center fragment convention is supported.
73
* ``PIPE_CAP_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the integer
74
pixel-center fragment convention is supported.
75
* ``PIPE_CAP_DEPTH_CLIP_DISABLE``: Whether the driver is capable of disabling
76
depth clipping (through pipe_rasterizer_state).
77
* ``PIPE_CAP_DEPTH_CLIP_DISABLE_SEPARATE``: Whether the driver is capable of
78
disabling depth clipping (through pipe_rasterizer_state) separately for
79
the near and far plane. If not, depth_clip_near and depth_clip_far will be
81
``PIPE_CAP_DEPTH_CLAMP_ENABLE``: Whether the driver is capable of
82
enabling depth clamping (through pipe_rasterizer_state) separately from depth
83
clipping. If not, depth_clamp will be the inverse of depth_clip_far.
84
* ``PIPE_CAP_SHADER_STENCIL_EXPORT``: Whether a stencil reference value can be
85
written from a fragment shader.
86
* ``PIPE_CAP_VS_INSTANCEID``: Whether ``SYSTEM_VALUE_INSTANCE_ID`` is
87
supported in the vertex shader.
88
* ``PIPE_CAP_VERTEX_ELEMENT_INSTANCE_DIVISOR``: Whether the driver supports
89
per-instance vertex attribs.
90
* ``PIPE_CAP_FRAGMENT_COLOR_CLAMPED``: Whether fragment color clamping is
91
supported. That is, is the pipe_rasterizer_state::clamp_fragment_color
92
flag supported by the driver? If not, gallium frontends will insert
93
clamping code into the fragment shaders when needed.
95
* ``PIPE_CAP_MIXED_COLORBUFFER_FORMATS``: Whether mixed colorbuffer formats are
96
supported, e.g. RGBA8 and RGBA32F as the first and second colorbuffer, resp.
97
* ``PIPE_CAP_VERTEX_COLOR_UNCLAMPED``: Whether the driver is capable of
98
outputting unclamped vertex colors from a vertex shader. If unsupported,
99
the vertex colors are always clamped. This is the default for DX9 hardware.
100
* ``PIPE_CAP_VERTEX_COLOR_CLAMPED``: Whether the driver is capable of
101
clamping vertex colors when they come out of a vertex shader, as specified
102
by the pipe_rasterizer_state::clamp_vertex_color flag. If unsupported,
103
the vertex colors are never clamped. This is the default for DX10 hardware.
104
If both clamped and unclamped CAPs are supported, the clamping can be
105
controlled through pipe_rasterizer_state. If the driver cannot do vertex
106
color clamping, gallium frontends may insert clamping code into the vertex
108
* ``PIPE_CAP_GLSL_FEATURE_LEVEL``: Whether the driver supports features
109
equivalent to a specific GLSL version. E.g. for GLSL 1.3, report 130.
110
* ``PIPE_CAP_GLSL_FEATURE_LEVEL_COMPATIBILITY``: Whether the driver supports
111
features equivalent to a specific GLSL version including all legacy OpenGL
112
features only present in the OpenGL compatibility profile.
113
The only legacy features that Gallium drivers must implement are
114
the legacy shader inputs and outputs (colors, texcoords, fog, clipvertex,
116
* ``PIPE_CAP_ESSL_FEATURE_LEVEL``: An optional cap to allow drivers to
117
report a higher GLSL version for GLES contexts. This is useful when a
118
driver does not support all the required features for a higher GL version,
119
but does support the required features for a higher GLES version. A driver
120
is allowed to return ``0`` in which case ``PIPE_CAP_GLSL_FEATURE_LEVEL`` is
122
Note that simply returning the same value as the GLSL feature level cap is
123
incorrect. For example, GLSL version 3.30 does not require ``ARB_gpu_shader5``,
124
but ESSL version 3.20 es does require ``EXT_gpu_shader5``
125
* ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION``: Whether quads adhere to
126
the flatshade_first setting in ``pipe_rasterizer_state``.
127
* ``PIPE_CAP_USER_VERTEX_BUFFERS``: Whether the driver supports user vertex
128
buffers. If not, gallium frontends must upload all data which is not in hw
129
resources. If user-space buffers are supported, the driver must also still
130
accept HW resource buffers.
131
* ``PIPE_CAP_VERTEX_BUFFER_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
132
limitation. If true, pipe_vertex_buffer::buffer_offset must always be aligned
133
to 4. If false, there are no restrictions on the offset.
134
* ``PIPE_CAP_VERTEX_BUFFER_STRIDE_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
135
limitation. If true, pipe_vertex_buffer::stride must always be aligned to 4.
136
If false, there are no restrictions on the stride.
137
* ``PIPE_CAP_VERTEX_ELEMENT_SRC_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes
138
a hw limitation. If true, pipe_vertex_element::src_offset must always be
139
aligned to 4. If false, there are no restrictions on src_offset.
140
* ``PIPE_CAP_VERTEX_ATTRIB_ELEMENT_ALIGNED_ONLY``: This CAP describes
141
a hw limitation. If true, the sum of
142
``pipe_vertex_element::src_offset + pipe_vertex_buffer::buffer_offset + pipe_vertex_buffer::stride``
143
must always be aligned to the component size for the vertex attributes
144
which access that buffer. If false, there are no restrictions on these values.
145
This CAP cannot be used with any other alignment-requiring CAPs.
146
* ``PIPE_CAP_COMPUTE``: Whether the implementation supports the
147
compute entry points defined in pipe_context and pipe_screen.
148
* ``PIPE_CAP_CONSTANT_BUFFER_OFFSET_ALIGNMENT``: Describes the required
149
alignment of pipe_constant_buffer::buffer_offset.
150
* ``PIPE_CAP_START_INSTANCE``: Whether the driver supports
151
pipe_draw_info::start_instance.
152
* ``PIPE_CAP_QUERY_TIMESTAMP``: Whether PIPE_QUERY_TIMESTAMP and
153
the pipe_screen::get_timestamp hook are implemented.
154
* ``PIPE_CAP_TEXTURE_MULTISAMPLE``: Whether all MSAA resources supported
155
for rendering are also supported for texturing.
156
* ``PIPE_CAP_MIN_MAP_BUFFER_ALIGNMENT``: The minimum alignment that should be
157
expected for a pointer returned by transfer_map if the resource is
158
PIPE_BUFFER. In other words, the pointer returned by transfer_map is
159
always aligned to this value.
160
* ``PIPE_CAP_TEXTURE_BUFFER_OFFSET_ALIGNMENT``: Describes the required
161
alignment for pipe_sampler_view::u.buf.offset, in bytes.
162
If a driver does not support offset/size, it should return 0.
163
* ``PIPE_CAP_BUFFER_SAMPLER_VIEW_RGBA_ONLY``: Whether the driver only
164
supports R, RG, RGB and RGBA formats for PIPE_BUFFER sampler views.
165
When this is the case it should be assumed that the swizzle parameters
166
in the sampler view have no effect.
167
* ``PIPE_CAP_TGSI_TEXCOORD``: This CAP describes a hw limitation.
168
If true, the hardware cannot replace arbitrary shader inputs with sprite
169
coordinates and hence the inputs that are desired to be replaceable must
170
be declared with TGSI_SEMANTIC_TEXCOORD instead of TGSI_SEMANTIC_GENERIC.
171
The rasterizer's sprite_coord_enable state therefore also applies to the
173
Also, TGSI_SEMANTIC_PCOORD becomes available, which labels a fragment shader
174
input that will always be replaced with sprite coordinates.
175
* ``PIPE_CAP_TEXTURE_BUFFER_SAMPLER``: Whether a sampler should still
176
be used for PIPE_BUFFER resources (normally a sampler is only used
177
if the texture target is PIPE_TEXTURE_*).
178
* ``PIPE_CAP_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_CAP_QUERY_PIPELINE_STATISTICS``: Whether PIPE_QUERY_PIPELINE_STATISTICS
187
* ``PIPE_CAP_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)
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_CAP_MAX_TEXTURE_BUFFER_SIZE``: The maximum accessible size with
199
a buffer sampler view, in texels.
200
* ``PIPE_CAP_MAX_VIEWPORTS``: The maximum number of viewports (and scissors
201
since they are linked) a driver can support. Returning 0 is equivalent
202
to returning 1 because every driver has to support at least a single
203
viewport/scissor combination.
204
* ``PIPE_CAP_ENDIANNESS``:: The endianness of the device. Either
205
PIPE_ENDIAN_BIG or PIPE_ENDIAN_LITTLE.
206
* ``PIPE_CAP_MIXED_FRAMEBUFFER_SIZES``: Whether it is allowed to have
207
different sizes for fb color/zs attachments. This controls whether
208
ARB_framebuffer_object is provided.
209
* ``PIPE_CAP_VS_LAYER_VIEWPORT``: Whether ``VARYING_SLOT_LAYER`` and
210
``VARYING_SLOT_VIEWPORT`` are supported as vertex shader outputs. Note that
211
the viewport will only be used if multiple viewports are exposed.
212
* ``PIPE_CAP_MAX_GEOMETRY_OUTPUT_VERTICES``: The maximum number of vertices
213
output by a single invocation of a geometry shader.
214
* ``PIPE_CAP_MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS``: The maximum number of
215
vertex components output by a single invocation of a geometry shader.
216
This is the product of the number of attribute components per vertex and
217
the number of output vertices.
218
* ``PIPE_CAP_MAX_TEXTURE_GATHER_COMPONENTS``: Max number of components
219
in format that texture gather can operate on. 1 == RED, ALPHA etc,
221
* ``PIPE_CAP_TEXTURE_GATHER_SM5``: Whether the texture gather
222
hardware implements the SM5 features, component selection,
223
shadow comparison, and run-time offsets.
224
* ``PIPE_CAP_BUFFER_MAP_PERSISTENT_COHERENT``: Whether
225
PIPE_MAP_PERSISTENT and PIPE_MAP_COHERENT are supported
227
* ``PIPE_CAP_TEXTURE_QUERY_LOD``: Whether the ``LODQ`` instruction is
229
* ``PIPE_CAP_MIN_TEXTURE_GATHER_OFFSET``: The minimum offset that can be used
230
in conjunction with a texture gather opcode.
231
* ``PIPE_CAP_MAX_TEXTURE_GATHER_OFFSET``: The maximum offset that can be used
232
in conjunction with a texture gather opcode.
233
* ``PIPE_CAP_SAMPLE_SHADING``: Whether there is support for per-sample
234
shading. The context->set_min_samples function will be expected to be
236
* ``PIPE_CAP_TEXTURE_GATHER_OFFSETS``: Whether the ``TG4`` instruction can
238
* ``PIPE_CAP_VS_WINDOW_SPACE_POSITION``: Whether window-space position is
239
supported, which disables clipping and viewport transformation.
240
* ``PIPE_CAP_MAX_VERTEX_STREAMS``: The maximum number of vertex streams
241
supported by the geometry shader. If stream-out is supported, this should be
242
at least 1. If stream-out is not supported, this should be 0.
243
* ``PIPE_CAP_DRAW_INDIRECT``: Whether the driver supports taking draw arguments
244
{ count, instance_count, start, index_bias } from a PIPE_BUFFER resource.
246
* ``PIPE_CAP_MULTI_DRAW_INDIRECT``: Whether the driver supports
247
pipe_draw_info::indirect_stride and ::indirect_count
248
* ``PIPE_CAP_MULTI_DRAW_INDIRECT_PARAMS``: Whether the driver supports
249
taking the number of indirect draws from a separate parameter
250
buffer, see pipe_draw_indirect_info::indirect_draw_count.
251
* ``PIPE_CAP_FS_FINE_DERIVATIVE``: Whether the fragment shader supports
252
the FINE versions of DDX/DDY.
253
* ``PIPE_CAP_VENDOR_ID``: The vendor ID of the underlying hardware. If it's
254
not available one should return 0xFFFFFFFF.
255
* ``PIPE_CAP_DEVICE_ID``: The device ID (PCI ID) of the underlying hardware.
256
0xFFFFFFFF if not available.
257
* ``PIPE_CAP_ACCELERATED``: Whether the renderer is hardware accelerated.
258
* ``PIPE_CAP_VIDEO_MEMORY``: The amount of video memory in megabytes.
259
* ``PIPE_CAP_UMA``: If the device has a unified memory architecture or on-card
261
* ``PIPE_CAP_CONDITIONAL_RENDER_INVERTED``: Whether the driver supports inverted
262
condition for conditional rendering.
263
* ``PIPE_CAP_MAX_VERTEX_ATTRIB_STRIDE``: The maximum supported vertex stride.
264
* ``PIPE_CAP_SAMPLER_VIEW_TARGET``: Whether the sampler view's target can be
265
different than the underlying resource's, as permitted by
266
ARB_texture_view. For example a 2d array texture may be reinterpreted as a
267
cube (array) texture and vice-versa.
268
* ``PIPE_CAP_CLIP_HALFZ``: Whether the driver supports the
269
pipe_rasterizer_state::clip_halfz being set to true. This is required
270
for enabling ARB_clip_control.
271
* ``PIPE_CAP_VERTEXID_NOBASE``: If true, the driver only supports
272
TGSI_SEMANTIC_VERTEXID_NOBASE (and not TGSI_SEMANTIC_VERTEXID). This means
273
gallium frontends for APIs whose vertexIDs are offset by basevertex (such as GL)
274
will need to lower TGSI_SEMANTIC_VERTEXID to TGSI_SEMANTIC_VERTEXID_NOBASE
275
and TGSI_SEMANTIC_BASEVERTEX, so drivers setting this must handle both these
276
semantics. Only relevant if geometry shaders are supported.
277
(BASEVERTEX could be exposed separately too via ``PIPE_CAP_DRAW_PARAMETERS``).
278
* ``PIPE_CAP_POLYGON_OFFSET_CLAMP``: If true, the driver implements support
279
for ``pipe_rasterizer_state::offset_clamp``.
280
* ``PIPE_CAP_MULTISAMPLE_Z_RESOLVE``: Whether the driver supports blitting
281
a multisampled depth buffer into a single-sampled texture (or depth buffer).
282
Only the first sampled should be copied.
283
* ``PIPE_CAP_RESOURCE_FROM_USER_MEMORY``: Whether the driver can create
284
a pipe_resource where an already-existing piece of (malloc'd) user memory
285
is used as its backing storage. In other words, whether the driver can map
286
existing user memory into the device address space for direct device access.
287
The create function is pipe_screen::resource_from_user_memory. The address
288
and size must be page-aligned.
289
* ``PIPE_CAP_RESOURCE_FROM_USER_MEMORY_COMPUTE_ONLY``: Same as
290
``PIPE_CAP_RESOURCE_FROM_USER_MEMORY`` but indicates it is only supported from
292
* ``PIPE_CAP_DEVICE_RESET_STATUS_QUERY``:
293
Whether pipe_context::get_device_reset_status is implemented.
294
* ``PIPE_CAP_MAX_SHADER_PATCH_VARYINGS``:
295
How many per-patch outputs and inputs are supported between tessellation
296
control and tessellation evaluation shaders, not counting in TESSINNER and
297
TESSOUTER. The minimum allowed value for OpenGL is 30.
298
* ``PIPE_CAP_TEXTURE_FLOAT_LINEAR``: Whether the linear minification and
299
magnification filters are supported with single-precision floating-point
301
* ``PIPE_CAP_TEXTURE_HALF_FLOAT_LINEAR``: Whether the linear minification and
302
magnification filters are supported with half-precision floating-point
304
* ``PIPE_CAP_DEPTH_BOUNDS_TEST``: Whether bounds_test, bounds_min, and
305
bounds_max states of pipe_depth_stencil_alpha_state behave according
306
to the GL_EXT_depth_bounds_test specification.
307
* ``PIPE_CAP_TEXTURE_QUERY_SAMPLES``: Whether the `TXQS` opcode is supported
308
* ``PIPE_CAP_FORCE_PERSAMPLE_INTERP``: If the driver can force per-sample
309
interpolation for all fragment shader inputs if
310
pipe_rasterizer_state::force_persample_interp is set. This is only used
311
by GL3-level sample shading (ARB_sample_shading). GL4-level sample shading
312
(ARB_gpu_shader5) doesn't use this. While GL3 hardware has a state for it,
313
GL4 hardware will likely need to emulate it with a shader variant, or by
314
selecting the interpolation weights with a conditional assignment
316
* ``PIPE_CAP_SHAREABLE_SHADERS``: Whether shader CSOs can be used by any
317
pipe_context. Important for reducing jank at draw time by letting GL shaders
318
linked in one thread be used in another thread without recompiling.
319
* ``PIPE_CAP_COPY_BETWEEN_COMPRESSED_AND_PLAIN_FORMATS``:
320
Whether copying between compressed and plain formats is supported where
321
a compressed block is copied to/from a plain pixel of the same size.
322
* ``PIPE_CAP_CLEAR_TEXTURE``: Whether `clear_texture` will be
323
available in contexts.
324
* ``PIPE_CAP_CLEAR_SCISSORED``: Whether `clear` can accept a scissored
326
* ``PIPE_CAP_DRAW_PARAMETERS``: Whether ``TGSI_SEMANTIC_BASEVERTEX``,
327
``TGSI_SEMANTIC_BASEINSTANCE``, and ``TGSI_SEMANTIC_DRAWID`` are
328
supported in vertex shaders.
329
* ``PIPE_CAP_SHADER_PACK_HALF_FLOAT``: Whether packed 16-bit float
330
packing/unpacking opcodes are supported.
331
* ``PIPE_CAP_FS_POSITION_IS_SYSVAL``: If gallium frontends should use a
332
system value for the POSITION fragment shader input.
333
* ``PIPE_CAP_FS_POINT_IS_SYSVAL``: If gallium frontends should use a system
334
value for the POINT fragment shader input.
335
* ``PIPE_CAP_FS_FACE_IS_INTEGER_SYSVAL``: If gallium frontends should use
336
a system value for the FACE fragment shader input.
337
Also, the FACE system value is integer, not float.
338
* ``PIPE_CAP_SHADER_BUFFER_OFFSET_ALIGNMENT``: Describes the required
339
alignment for pipe_shader_buffer::buffer_offset, in bytes. Maximum
340
value allowed is 256 (for GL conformance). 0 is only allowed if
341
shader buffers are not supported.
342
* ``PIPE_CAP_INVALIDATE_BUFFER``: Whether the use of ``invalidate_resource``
343
for buffers is supported.
344
* ``PIPE_CAP_GENERATE_MIPMAP``: Indicates whether pipe_context::generate_mipmap
346
* ``PIPE_CAP_STRING_MARKER``: Whether pipe->emit_string_marker() is supported.
347
* ``PIPE_CAP_SURFACE_REINTERPRET_BLOCKS``: Indicates whether
348
pipe_context::create_surface supports reinterpreting a texture as a surface
349
of a format with different block width/height (but same block size in bits).
350
For example, a compressed texture image can be interpreted as a
351
non-compressed surface whose texels are the same number of bits as the
352
compressed blocks, and vice versa. The width and height of the surface is
353
adjusted appropriately.
354
* ``PIPE_CAP_QUERY_BUFFER_OBJECT``: Driver supports
355
context::get_query_result_resource callback.
356
* ``PIPE_CAP_PCI_GROUP``: Return the PCI segment group number.
357
* ``PIPE_CAP_PCI_BUS``: Return the PCI bus number.
358
* ``PIPE_CAP_PCI_DEVICE``: Return the PCI device number.
359
* ``PIPE_CAP_PCI_FUNCTION``: Return the PCI function number.
360
* ``PIPE_CAP_FRAMEBUFFER_NO_ATTACHMENT``:
361
If non-zero, rendering to framebuffers with no surface attachments
362
is supported. The context->is_format_supported function will be expected
363
to be implemented with PIPE_FORMAT_NONE yeilding the MSAA modes the hardware
364
supports. N.B., The maximum number of layers supported for rasterizing a
365
primitive on a layer is obtained from ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS``
366
even though it can be larger than the number of layers supported by either
367
rendering or textures.
368
* ``PIPE_CAP_ROBUST_BUFFER_ACCESS_BEHAVIOR``: Implementation uses bounds
369
checking on resource accesses by shader if the context is created with
370
PIPE_CONTEXT_ROBUST_BUFFER_ACCESS. See the ARB_robust_buffer_access_behavior
371
extension for information on the required behavior for out of bounds accesses
372
and accesses to unbound resources.
373
* ``PIPE_CAP_CULL_DISTANCE``: Whether the driver supports the arb_cull_distance
374
extension and thus implements proper support for culling planes.
375
* ``PIPE_CAP_CULL_DISTANCE_NOCOMBINE``: Whether the driver wants to skip
376
running the `nir_lower_clip_cull_distance_arrays` pass in order to get
377
VARYING_SLOT_CULL_DIST0 slot variables.
378
* ``PIPE_CAP_PRIMITIVE_RESTART_FOR_PATCHES``: Whether primitive restart is
379
supported for patch primitives.
380
* ``PIPE_CAP_SHADER_GROUP_VOTE``: Whether the ``VOTE_*`` ops can be used in
382
* ``PIPE_CAP_MAX_WINDOW_RECTANGLES``: The maxium number of window rectangles
383
supported in ``set_window_rectangles``.
384
* ``PIPE_CAP_POLYGON_OFFSET_UNITS_UNSCALED``: If true, the driver implements support
385
for ``pipe_rasterizer_state::offset_units_unscaled``.
386
* ``PIPE_CAP_VIEWPORT_SUBPIXEL_BITS``: Number of bits of subpixel precision for
387
floating point viewport bounds.
388
* ``PIPE_CAP_RASTERIZER_SUBPIXEL_BITS``: Number of bits of subpixel precision used
390
* ``PIPE_CAP_MIXED_COLOR_DEPTH_BITS``: Whether there is non-fallback
391
support for color/depth format combinations that use a different
392
number of bits. For the purpose of this cap, Z24 is treated as
393
32-bit. If set to off, that means that a B5G6R5 + Z24 or RGBA8 + Z16
394
combination will require a driver fallback, and should not be
395
advertised in the GLX/EGL config list.
396
* ``PIPE_CAP_SHADER_ARRAY_COMPONENTS``: If true, the driver interprets the
397
UsageMask of input and output declarations and allows declaring arrays
398
in overlapping ranges. The components must be a contiguous range, e.g. a
399
UsageMask of xy or yzw is allowed, but xz or yw isn't. Declarations with
400
overlapping locations must have matching semantic names and indices, and
401
equal interpolation qualifiers.
402
Components may overlap, notably when the gaps in an array of dvec3 are
404
* ``PIPE_CAP_STREAM_OUTPUT_PAUSE_RESUME``: Whether GL_ARB_transform_feeddback2
405
is supported, including pausing/resuming queries and having
406
`count_from_stream_output` set on indirect draws to implement
407
glDrawTransformFeedback. Required for OpenGL 4.0.
408
* ``PIPE_CAP_STREAM_OUTPUT_INTERLEAVE_BUFFERS``: Whether interleaved stream
409
output mode is able to interleave across buffers. This is required for
410
ARB_transform_feedback3.
411
* ``PIPE_CAP_SHADER_CAN_READ_OUTPUTS``: Whether every TGSI shader stage can read
412
from the output file.
413
* ``PIPE_CAP_GLSL_OPTIMIZE_CONSERVATIVELY``: Tell the GLSL compiler to use
414
the minimum amount of optimizations just to be able to do all the linking
416
* ``PIPE_CAP_FBFETCH``: The number of render targets whose value in the
417
current framebuffer can be read in the shader. 0 means framebuffer fetch
418
is not supported. 1 means that only the first render target can be read,
419
and a larger value would mean that multiple render targets are supported.
420
* ``PIPE_CAP_FBFETCH_COHERENT``: Whether framebuffer fetches from the fragment
421
shader can be guaranteed to be coherent with framebuffer writes.
422
* ``PIPE_CAP_TGSI_MUL_ZERO_WINS``: Whether TGSI shaders support the
423
``TGSI_PROPERTY_MUL_ZERO_WINS`` shader property.
424
* ``PIPE_CAP_DOUBLES``: Whether double precision floating-point operations
426
* ``PIPE_CAP_INT64``: Whether 64-bit integer operations are supported.
427
* ``PIPE_CAP_INT64_DIVMOD``: Whether 64-bit integer division/modulo
428
operations are supported.
429
* ``PIPE_CAP_TGSI_TEX_TXF_LZ``: Whether TEX_LZ and TXF_LZ opcodes are
431
* ``PIPE_CAP_SHADER_CLOCK``: Whether the CLOCK opcode is supported.
432
* ``PIPE_CAP_POLYGON_MODE_FILL_RECTANGLE``: Whether the
433
PIPE_POLYGON_MODE_FILL_RECTANGLE mode is supported for
434
``pipe_rasterizer_state::fill_front`` and
435
``pipe_rasterizer_state::fill_back``.
436
* ``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``: The page size of sparse buffers in
437
bytes, or 0 if sparse buffers are not supported. The page size must be at
439
* ``PIPE_CAP_SHADER_BALLOT``: Whether the BALLOT and READ_* opcodes as well as
440
the SUBGROUP_* semantics are supported.
441
* ``PIPE_CAP_TES_LAYER_VIEWPORT``: Whether ``VARYING_SLOT_LAYER`` and
442
``VARYING_SLOT_VIEWPORT`` are supported as tessellation evaluation
444
* ``PIPE_CAP_CAN_BIND_CONST_BUFFER_AS_VERTEX``: Whether a buffer with just
445
PIPE_BIND_CONSTANT_BUFFER can be legally passed to set_vertex_buffers.
446
* ``PIPE_CAP_ALLOW_MAPPED_BUFFERS_DURING_EXECUTION``: As the name says.
447
* ``PIPE_CAP_POST_DEPTH_COVERAGE``: whether
448
``TGSI_PROPERTY_FS_POST_DEPTH_COVERAGE`` is supported.
449
* ``PIPE_CAP_BINDLESS_TEXTURE``: Whether bindless texture operations are
451
* ``PIPE_CAP_NIR_SAMPLERS_AS_DEREF``: Whether NIR tex instructions should
452
reference texture and sampler as NIR derefs instead of by indices.
453
* ``PIPE_CAP_QUERY_SO_OVERFLOW``: Whether the
454
``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` and
455
``PIPE_QUERY_SO_OVERFLOW_ANY_PREDICATE`` query types are supported. Note that
456
for a driver that does not support multiple output streams (i.e.,
457
``PIPE_CAP_MAX_VERTEX_STREAMS`` is 1), both query types are identical.
458
* ``PIPE_CAP_MEMOBJ``: Whether operations on memory objects are supported.
459
* ``PIPE_CAP_LOAD_CONSTBUF``: True if the driver supports ``TGSI_OPCODE_LOAD`` use
460
with constant buffers.
461
* ``PIPE_CAP_TILE_RASTER_ORDER``: Whether the driver supports
462
GL_MESA_tile_raster_order, using the tile_raster_order_* fields in
463
pipe_rasterizer_state.
464
* ``PIPE_CAP_MAX_COMBINED_SHADER_OUTPUT_RESOURCES``: Limit on combined shader
465
output resources (images + buffers + fragment outputs). If 0 the state
466
tracker works it out.
467
* ``PIPE_CAP_FRAMEBUFFER_MSAA_CONSTRAINTS``: This determines limitations
468
on the number of samples that framebuffer attachments can have.
471
0. color.nr_samples == zs.nr_samples == color.nr_storage_samples
472
(standard MSAA quality)
473
1. color.nr_samples >= zs.nr_samples == color.nr_storage_samples
474
(enhanced MSAA quality)
475
2. color.nr_samples >= zs.nr_samples >= color.nr_storage_samples
476
(full flexibility in tuning MSAA quality and performance)
478
All color attachments must have the same number of samples and the same
479
number of storage samples.
480
* ``PIPE_CAP_SIGNED_VERTEX_BUFFER_OFFSET``:
481
Whether pipe_vertex_buffer::buffer_offset is treated as signed. The u_vbuf
482
module needs this for optimal performance in workstation applications.
483
* ``PIPE_CAP_CONTEXT_PRIORITY_MASK``: For drivers that support per-context
484
priorities, this returns a bitmask of ``PIPE_CONTEXT_PRIORITY_x`` for the
485
supported priority levels. A driver that does not support prioritized
486
contexts can return 0.
487
* ``PIPE_CAP_FENCE_SIGNAL``: True if the driver supports signaling semaphores
488
using fence_server_signal().
489
* ``PIPE_CAP_CONSTBUF0_FLAGS``: The bits of pipe_resource::flags that must be
490
set when binding that buffer as constant buffer 0. If the buffer doesn't have
491
those bits set, pipe_context::set_constant_buffer(.., 0, ..) is ignored
492
by the driver, and the driver can throw assertion failures.
493
* ``PIPE_CAP_PACKED_UNIFORMS``: True if the driver supports packed uniforms
494
as opposed to padding to vec4s. Requires ``PIPE_SHADER_CAP_INTEGERS`` if
495
``lower_uniforms_to_ubo`` is set.
496
* ``PIPE_CAP_CONSERVATIVE_RASTER_POST_SNAP_TRIANGLES``: Whether the
497
``PIPE_CONSERVATIVE_RASTER_POST_SNAP`` mode is supported for triangles.
498
The post-snap mode means the conservative rasterization occurs after
499
the conversion from floating-point to fixed-point coordinates
500
on the subpixel grid.
501
* ``PIPE_CAP_CONSERVATIVE_RASTER_POST_SNAP_POINTS_LINES``: Whether the
502
``PIPE_CONSERVATIVE_RASTER_POST_SNAP`` mode is supported for points and lines.
503
* ``PIPE_CAP_CONSERVATIVE_RASTER_PRE_SNAP_TRIANGLES``: Whether the
504
``PIPE_CONSERVATIVE_RASTER_PRE_SNAP`` mode is supported for triangles.
505
The pre-snap mode means the conservative rasterization occurs before
506
the conversion from floating-point to fixed-point coordinates.
507
* ``PIPE_CAP_CONSERVATIVE_RASTER_PRE_SNAP_POINTS_LINES``: Whether the
508
``PIPE_CONSERVATIVE_RASTER_PRE_SNAP`` mode is supported for points and lines.
509
* ``PIPE_CAP_CONSERVATIVE_RASTER_POST_DEPTH_COVERAGE``: Whether
510
``PIPE_CAP_POST_DEPTH_COVERAGE`` works with conservative rasterization.
511
* ``PIPE_CAP_CONSERVATIVE_RASTER_INNER_COVERAGE``: Whether
512
inner_coverage from GL_INTEL_conservative_rasterization is supported.
513
* ``PIPE_CAP_MAX_CONSERVATIVE_RASTER_SUBPIXEL_PRECISION_BIAS``: The maximum
514
subpixel precision bias in bits during conservative rasterization.
515
* ``PIPE_CAP_PROGRAMMABLE_SAMPLE_LOCATIONS``: True is the driver supports
516
programmable sample location through ```get_sample_pixel_grid``` and
517
```set_sample_locations```.
518
* ``PIPE_CAP_MAX_GS_INVOCATIONS``: Maximum supported value of
519
TGSI_PROPERTY_GS_INVOCATIONS.
520
* ``PIPE_CAP_MAX_SHADER_BUFFER_SIZE``: Maximum supported size for binding
521
with set_shader_buffers.
522
* ``PIPE_CAP_MAX_COMBINED_SHADER_BUFFERS``: Maximum total number of shader
523
buffers. A value of 0 means the sum of all per-shader stage maximums (see
524
``PIPE_SHADER_CAP_MAX_SHADER_BUFFERS``).
525
* ``PIPE_CAP_MAX_COMBINED_HW_ATOMIC_COUNTERS``: Maximum total number of atomic
526
counters. A value of 0 means the default value (MAX_ATOMIC_COUNTERS = 4096).
527
* ``PIPE_CAP_MAX_COMBINED_HW_ATOMIC_COUNTER_BUFFERS``: Maximum total number of
528
atomic counter buffers. A value of 0 means the sum of all per-shader stage
529
maximums (see ``PIPE_SHADER_CAP_MAX_HW_ATOMIC_COUNTER_BUFFERS``).
530
* ``PIPE_CAP_MAX_TEXTURE_UPLOAD_MEMORY_BUDGET``: Maximum recommend memory size
531
for all active texture uploads combined. This is a performance hint.
533
* ``PIPE_CAP_MAX_VERTEX_ELEMENT_SRC_OFFSET``: The maximum supported value for
534
of pipe_vertex_element::src_offset.
535
* ``PIPE_CAP_SURFACE_SAMPLE_COUNT``: Whether the driver
536
supports pipe_surface overrides of resource nr_samples. If set, will
537
enable EXT_multisampled_render_to_texture.
538
* ``PIPE_CAP_IMAGE_ATOMIC_FLOAT_ADD``: Atomic floating point adds are
539
supported on images, buffers, and shared memory.
540
* ``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.
541
* ``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.
542
* ``PIPE_CAP_DEST_SURFACE_SRGB_CONTROL``: Indicates whether the drivers
543
supports switching the format between sRGB and linear for a surface that is
544
used as destination in draw and blit calls.
545
* ``PIPE_CAP_NIR_COMPACT_ARRAYS``: True if the compiler backend supports NIR's compact array feature, for all shader stages.
546
* ``PIPE_CAP_MAX_VARYINGS``: The maximum number of fragment shader
547
varyings. This will generally correspond to
548
``PIPE_SHADER_CAP_MAX_INPUTS`` for the fragment shader, but in some
549
cases may be a smaller number.
550
* ``PIPE_CAP_COMPUTE_GRID_INFO_LAST_BLOCK``: Whether pipe_grid_info::last_block
551
is implemented by the driver. See struct pipe_grid_info for more details.
552
* ``PIPE_CAP_COMPUTE_SHADER_DERIVATIVE``: True if the driver supports derivatives (and texture lookups with implicit derivatives) in compute shaders.
553
* ``PIPE_CAP_TGSI_SKIP_SHRINK_IO_ARRAYS``: Whether the TGSI pass to shrink IO
554
arrays should be skipped and enforce keeping the declared array sizes instead.
555
A driver might rely on the input mapping that was defined with the original
557
* ``PIPE_CAP_IMAGE_LOAD_FORMATTED``: True if a format for image loads does not need to be specified in the shader IR
558
* ``PIPE_CAP_IMAGE_STORE_FORMATTED``: True if a format for image stores does not need to be specified in the shader IR
559
* ``PIPE_CAP_THROTTLE``: Whether or not gallium frontends should throttle pipe_context
560
execution. 0 = throttling is disabled.
561
* ``PIPE_CAP_DMABUF``: Whether Linux DMABUF handles are supported by
562
resource_from_handle and resource_get_handle.
563
* ``PIPE_CAP_PREFER_COMPUTE_FOR_MULTIMEDIA``: Whether VDPAU, VAAPI, and
564
OpenMAX should use a compute-based blit instead of pipe_context::blit and compute pipeline for compositing images.
565
* ``PIPE_CAP_FRAGMENT_SHADER_INTERLOCK``: True if fragment shader interlock
566
functionality is supported.
567
* ``PIPE_CAP_CS_DERIVED_SYSTEM_VALUES_SUPPORTED``: True if driver handles
568
gl_LocalInvocationIndex and gl_GlobalInvocationID. Otherwise, gallium frontends will
569
lower those system values.
570
* ``PIPE_CAP_ATOMIC_FLOAT_MINMAX``: Atomic float point minimum,
571
maximum, exchange and compare-and-swap support to buffer and shared variables.
572
* ``PIPE_CAP_TGSI_DIV``: Whether opcode DIV is supported
573
* ``PIPE_CAP_FRAGMENT_SHADER_TEXTURE_LOD``: Whether texture lookups with
574
explicit LOD is supported in the fragment shader.
575
* ``PIPE_CAP_FRAGMENT_SHADER_DERIVATIVES``: True if the driver supports
576
derivatives in fragment shaders.
577
* ``PIPE_CAP_VERTEX_SHADER_SATURATE``: True if the driver supports saturate
578
modifiers in the vertex shader.
579
* ``PIPE_CAP_TEXTURE_SHADOW_LOD``: True if the driver supports shadow sampler
580
types with texture functions having interaction with LOD of texture lookup.
581
* ``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.
582
* ``PIPE_CAP_IMAGE_ATOMIC_INC_WRAP``: Atomic increment/decrement + wrap around
584
* ``PIPE_CAP_PREFER_IMM_ARRAYS_AS_CONSTBUF``: True if gallium frontends should
585
turn arrays whose contents can be deduced at compile time into constant
586
buffer loads, or false if the driver can handle such arrays itself in a more
588
* ``PIPE_CAP_GL_SPIRV``: True if the driver supports ARB_gl_spirv extension.
589
* ``PIPE_CAP_GL_SPIRV_VARIABLE_POINTERS``: True if the driver supports Variable Pointers in SPIR-V shaders.
590
* ``PIPE_CAP_DEMOTE_TO_HELPER_INVOCATION``: True if driver supports demote keyword in GLSL programs.
591
* ``PIPE_CAP_TGSI_TG4_COMPONENT_IN_SWIZZLE``: True if driver wants the TG4 component encoded in sampler swizzle rather than as a separate source.
592
* ``PIPE_CAP_FLATSHADE``: Driver supports pipe_rasterizer_state::flatshade. Must be 1
593
for non-NIR drivers or gallium nine.
594
* ``PIPE_CAP_ALPHA_TEST``: Driver supports alpha-testing. Must be 1
595
for non-NIR drivers or gallium nine. If set, frontend may set
596
``pipe_depth_stencil_alpha_state->alpha_enabled`` and ``alpha_func``.
597
Otherwise, alpha test will be lowered to a comparison and discard_if in the
599
* ``PIPE_CAP_POINT_SIZE_FIXED``: Driver supports point-sizes that are fixed,
600
as opposed to writing gl_PointSize for every point.
601
* ``PIPE_CAP_TWO_SIDED_COLOR``: Driver supports two-sided coloring. Must be 1
602
for non-NIR drivers. If set, pipe_rasterizer_state may be set to indicate
603
that backfacing primitives should use the back-side color as the FS input
604
color. If unset, mesa/st will lower it to gl_FrontFacing reads in the
606
* ``PIPE_CAP_CLIP_PLANES``: Driver supports user-defined clip-planes. 0 denotes none, 1 denotes MAX_CLIP_PLANES. > 1 overrides MAX.
607
* ``PIPE_CAP_MAX_VERTEX_BUFFERS``: Number of supported vertex buffers.
608
* ``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.
609
* ``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.
610
* ``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.
611
* ``PIPE_CAP_PACKED_STREAM_OUTPUT``: Driver supports packing optimization for stream output (e.g. GL transform feedback captured variables). Defaults to true.
612
* ``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.
613
* ``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.
614
* ``PIPE_CAP_GL_BEGIN_END_BUFFER_SIZE``: Buffer size used to upload vertices for glBegin/glEnd.
615
* ``PIPE_CAP_VIEWPORT_SWIZZLE``: Whether pipe_viewport_state::swizzle can be used to specify pre-clipping swizzling of coordinates (see GL_NV_viewport_swizzle).
616
* ``PIPE_CAP_SYSTEM_SVM``: True if all application memory can be shared with the GPU without explicit mapping.
617
* ``PIPE_CAP_VIEWPORT_MASK``: Whether ``TGSI_SEMANTIC_VIEWPORT_MASK`` and ``TGSI_PROPERTY_LAYER_VIEWPORT_RELATIVE`` are supported (see GL_NV_viewport_array2).
618
* ``PIPE_CAP_MAP_UNSYNCHRONIZED_THREAD_SAFE``: Whether mapping a buffer as unsynchronized from any thread is safe.
619
* ``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.
620
* ``PIPE_CAP_BLEND_EQUATION_ADVANCED``: Driver supports blend equation advanced without necessarily supporting FBFETCH.
621
* ``PIPE_CAP_NIR_ATOMICS_AS_DEREF``: Whether NIR atomics instructions should reference atomics as NIR derefs instead of by indices.
622
* ``PIPE_CAP_NO_CLIP_ON_COPY_TEX``: Driver doesn't want x/y/width/height clipped based on src size when doing a copy texture operation (eg: may want out-of-bounds reads that produce 0 instead of leaving the texture content undefined)
623
* ``PIPE_CAP_MAX_TEXTURE_MB``: Maximum texture size in MB (default is 1024)
624
* ``PIPE_CAP_DEVICE_PROTECTED_CONTENT``: Whether the device support protected / encrypted content.
625
* ``PIPE_CAP_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 codepath in a gallium frontend for drivers that really prefer a real buffer.
626
* ``PIPE_CAP_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.
627
* ``PIPE_CAP_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.
628
* ``PIPE_CAP_SAMPLER_REDUCTION_MINMAX``: Driver supports EXT min/max sampler reduction.
629
* ``PIPE_CAP_SAMPLER_REDUCTION_MINMAX_ARB``: Driver supports ARB min/max sampler reduction with format queries.
630
* ``PIPE_CAP_EMULATE_NONFIXED_PRIMITIVE_RESTART``: Driver requests all draws using a non-fixed restart index to be rewritten to use a fixed restart index.
631
* ``PIPE_CAP_SUPPORTED_PRIM_MODES``: A bitmask of the ``pipe_prim_type`` enum values that the driver can natively support.
632
* ``PIPE_CAP_SUPPORTED_PRIM_MODES_WITH_RESTART``: A bitmask of the ``pipe_prim_type`` enum values that the driver can natively support for primitive restart. Only useful if ``PIPE_CAP_PRIMITIVE_RESTART`` is also exported.
633
* ``PIPE_CAP_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.
634
* ``PIPE_CAP_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.
635
* ``PIPE_CAP_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
636
* ``PIPE_CAP_MAX_SPARSE_TEXTURE_SIZE``: Maximum 1D/2D/rectangle texture image dimension for a sparse texture.
637
* ``PIPE_CAP_MAX_SPARSE_3D_TEXTURE_SIZE``: Maximum 3D texture image dimension for a sparse texture.
638
* ``PIPE_CAP_MAX_SPARSE_ARRAY_TEXTURE_LAYERS``: Maximum number of layers in a sparse array texture.
639
* ``PIPE_CAP_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 ARB_sparse_texture extension spec.
640
* ``PIPE_CAP_QUERY_SPARSE_TEXTURE_RESIDENCY``: TRUE if shader sparse texture sample instruction could also return the residency information.
641
* ``PIPE_CAP_CLAMP_SPARSE_TEXTURE_LOD``: TRUE if shader sparse texture sample instruction support clamp the minimal lod to prevent read from un-committed pages.
648
The floating-point capabilities are:
650
* ``PIPE_CAPF_MIN_LINE_WIDTH``: The minimum width of a regular line.
651
* ``PIPE_CAPF_MIN_LINE_WIDTH_AA``: The minimum width of a smoothed line.
652
* ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line.
653
* ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
654
* ``PIPE_CAPF_LINE_WIDTH_GRANULARITY``: The line width is rounded to a multiple of this number.
655
* ``PIPE_CAPF_MIN_POINT_SIZE``: The minimum width and height of a point.
656
* ``PIPE_CAPF_MIN_POINT_SIZE_AA``: The minimum width and height of a smoothed point.
657
* ``PIPE_CAPF_MAX_POINT_SIZE``: The maximum width and height of a point.
658
* ``PIPE_CAPF_MAX_POINT_SIZE_AA``: The maximum width and height of a smoothed point.
659
* ``PIPE_CAPF_POINT_SIZE_GRANULARITY``: The point size is rounded to a multiple of this number.
660
* ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
661
applied to anisotropically filtered textures.
662
* ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
663
to filtered textures.
664
* ``PIPE_CAPF_MIN_CONSERVATIVE_RASTER_DILATE``: The minimum conservative rasterization
666
* ``PIPE_CAPF_MAX_CONSERVATIVE_RASTER_DILATE``: The maximum conservative rasterization
668
* ``PIPE_CAPF_CONSERVATIVE_RASTER_DILATE_GRANULARITY``: The conservative rasterization
669
dilation granularity for values relative to the minimum dilation.
677
These are per-shader-stage capabitity queries. Different shader stages may
678
support different features.
680
* ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions.
681
* ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
682
* ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
683
* ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections.
684
* ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
685
* ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers.
686
* ``PIPE_SHADER_CAP_MAX_OUTPUTS``: The maximum number of output registers.
687
This is valid for all shaders except the fragment shader.
688
* ``PIPE_SHADER_CAP_MAX_CONST_BUFFER_SIZE``: The maximum size per constant buffer in bytes.
689
* ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
690
to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
691
only permit binding one constant buffer per shader.
693
If a value greater than 0 is returned, the driver can have multiple
694
constant buffers bound to shader stages. The CONST register file is
695
accessed with two-dimensional indices, like in the example below.
697
DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
698
DCL CONST[3][0] # declare first vector of constbuf 3
699
MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
701
* ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers.
702
* ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported.
703
* ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing
704
of the input file is supported.
705
* ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing
706
of the output file is supported.
707
* ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing
708
of the temporary file is supported.
709
* ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing
710
of the constant file is supported.
711
* ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e.
712
BGNSUB, ENDSUB, CAL, and RET, including RET in the main block.
713
* ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported.
714
If unsupported, only float opcodes are supported.
715
* ``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.
716
* ``PIPE_SHADER_CAP_FP16``: Whether half precision floating-point opcodes are supported.
717
If unsupported, half precision ops need to be lowered to full precision.
718
* ``PIPE_SHADER_CAP_FP16_DERIVATIVES``: Whether half precision floating-point
719
DDX and DDY opcodes are supported.
720
* ``PIPE_SHADER_CAP_FP16_CONST_BUFFERS``: Whether half precision floating-point
721
constant buffer loads are supported. Drivers are recommended to report 0
722
if x86 F16C is not supported by the CPU (or an equivalent instruction set
723
on other CPU architectures), otherwise they could be impacted by emulated
724
FP16 conversions in glUniform.
725
* ``PIPE_SHADER_CAP_INT16``: Whether 16-bit signed and unsigned integer types
727
* ``PIPE_SHADER_CAP_GLSL_16BIT_CONSTS``: Lower mediump constants to 16-bit.
728
Note that 16-bit constants are not lowered to uniforms in GLSL.
729
* ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: The maximum number of texture
731
* ``PIPE_SHADER_CAP_PREFERRED_IR``: Preferred representation of the
732
program. It should be one of the ``pipe_shader_ir`` enum values.
733
* ``PIPE_SHADER_CAP_MAX_SAMPLER_VIEWS``: The maximum number of texture
734
sampler views. Must not be lower than PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS.
735
* ``PIPE_SHADER_CAP_TGSI_DROUND_SUPPORTED``: Whether double precision rounding
736
is supported. If it is, DTRUNC/DCEIL/DFLR/DROUND opcodes may be used.
737
* ``PIPE_SHADER_CAP_TGSI_DFRACEXP_DLDEXP_SUPPORTED``: Whether DFRACEXP and
738
DLDEXP are supported.
739
* ``PIPE_SHADER_CAP_TGSI_LDEXP_SUPPORTED``: Whether LDEXP is supported.
740
* ``PIPE_SHADER_CAP_TGSI_FMA_SUPPORTED``: Whether FMA and DFMA (doubles only)
742
* ``PIPE_SHADER_CAP_TGSI_ANY_INOUT_DECL_RANGE``: Whether the driver doesn't
743
ignore tgsi_declaration_range::Last for shader inputs and outputs.
744
* ``PIPE_SHADER_CAP_MAX_UNROLL_ITERATIONS_HINT``: This is the maximum number
745
of iterations that loops are allowed to have to be unrolled. It is only
746
a hint to gallium frontends. Whether any loops will be unrolled is not
748
* ``PIPE_SHADER_CAP_MAX_SHADER_BUFFERS``: Maximum number of memory buffers
749
(also used to implement atomic counters). Having this be non-0 also
750
implies support for the ``LOAD``, ``STORE``, and ``ATOM*`` TGSI
752
* ``PIPE_SHADER_CAP_SUPPORTED_IRS``: Supported representations of the
753
program. It should be a mask of ``pipe_shader_ir`` bits.
754
* ``PIPE_SHADER_CAP_MAX_SHADER_IMAGES``: Maximum number of image units.
755
* ``PIPE_SHADER_CAP_LOWER_IF_THRESHOLD``: IF and ELSE branches with a lower
756
cost than this value should be lowered by gallium frontends for better
757
performance. This is a tunable for the GLSL compiler and the behavior is
758
specific to the compiler.
759
* ``PIPE_SHADER_CAP_TGSI_SKIP_MERGE_REGISTERS``: Whether the merge registers
760
TGSI pass is skipped. This might reduce code size and register pressure if
761
the underlying driver has a real backend compiler.
762
* ``PIPE_SHADER_CAP_MAX_HW_ATOMIC_COUNTERS``: If atomic counters are separate,
763
how many HW counters are available for this stage. (0 uses SSBO atomics).
764
* ``PIPE_SHADER_CAP_MAX_HW_ATOMIC_COUNTER_BUFFERS``: If atomic counters are
765
separate, how many atomic counter buffers are available for this stage.
767
.. _pipe_compute_cap:
772
Compute-specific capabilities. They can be queried using
773
pipe_screen::get_compute_param.
775
* ``PIPE_COMPUTE_CAP_IR_TARGET``: A description of the target of the form
776
``processor-arch-manufacturer-os`` that will be passed on to the compiler.
777
This CAP is only relevant for drivers that specify PIPE_SHADER_IR_NATIVE for
779
Value type: null-terminated string. Shader IR type dependent.
780
* ``PIPE_COMPUTE_CAP_GRID_DIMENSION``: Number of supported dimensions
781
for grid and block coordinates. Value type: ``uint64_t``. Shader IR type dependent.
782
* ``PIPE_COMPUTE_CAP_MAX_GRID_SIZE``: Maximum grid size in block
783
units. Value type: ``uint64_t []``. Shader IR type dependent.
784
* ``PIPE_COMPUTE_CAP_MAX_BLOCK_SIZE``: Maximum block size in thread
785
units. Value type: ``uint64_t []``. Shader IR type dependent.
786
* ``PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK``: Maximum number of threads that
787
a single block can contain. Value type: ``uint64_t``. Shader IR type dependent.
788
This may be less than the product of the components of MAX_BLOCK_SIZE and is
789
usually limited by the number of threads that can be resident simultaneously
791
* ``PIPE_COMPUTE_CAP_MAX_GLOBAL_SIZE``: Maximum size of the GLOBAL
792
resource. Value type: ``uint64_t``. Shader IR type dependent.
793
* ``PIPE_COMPUTE_CAP_MAX_LOCAL_SIZE``: Maximum size of the LOCAL
794
resource. Value type: ``uint64_t``. Shader IR type dependent.
795
* ``PIPE_COMPUTE_CAP_MAX_PRIVATE_SIZE``: Maximum size of the PRIVATE
796
resource. Value type: ``uint64_t``. Shader IR type dependent.
797
* ``PIPE_COMPUTE_CAP_MAX_INPUT_SIZE``: Maximum size of the INPUT
798
resource. Value type: ``uint64_t``. Shader IR type dependent.
799
* ``PIPE_COMPUTE_CAP_MAX_MEM_ALLOC_SIZE``: Maximum size of a memory object
800
allocation in bytes. Value type: ``uint64_t``.
801
* ``PIPE_COMPUTE_CAP_MAX_CLOCK_FREQUENCY``: Maximum frequency of the GPU
802
clock in MHz. Value type: ``uint32_t``
803
* ``PIPE_COMPUTE_CAP_MAX_COMPUTE_UNITS``: Maximum number of compute units
804
Value type: ``uint32_t``
805
* ``PIPE_COMPUTE_CAP_IMAGES_SUPPORTED``: Whether images are supported
806
non-zero means yes, zero means no. Value type: ``uint32_t``
807
* ``PIPE_COMPUTE_CAP_SUBGROUP_SIZE``: The size of a basic execution unit in
808
threads. Also known as wavefront size, warp size or SIMD width.
809
* ``PIPE_COMPUTE_CAP_ADDRESS_BITS``: The default compute device address space
810
size specified as an unsigned integer value in bits.
811
* ``PIPE_COMPUTE_CAP_MAX_VARIABLE_THREADS_PER_BLOCK``: Maximum variable number
812
of threads that a single block can contain. This is similar to
813
PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK, except that the variable size is not
814
known a compile-time but at dispatch-time.
821
These flags indicate how a resource will be used and are specified at resource
822
creation time. Resources may be used in different roles
823
during their lifecycle. Bind flags are cumulative and may be combined to create
824
a resource which can be used for multiple things.
825
Depending on the pipe driver's memory management and these bind flags,
826
resources might be created and handled quite differently.
828
* ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
829
rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs
830
must have this flag set.
831
* ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
832
depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
834
* ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to
835
query whether a device supports blending for a given format.
836
If this flag is set, surface creation may fail if blending is not supported
837
for the specified format. If it is not set, a driver may choose to ignore
838
blending on surfaces with formats that would require emulation.
839
* ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
840
pipe_screen::flush_front_buffer must have this flag set.
841
* ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
843
* ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
844
* ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
845
* ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
846
* ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer.
847
* ``PIPE_BIND_CUSTOM``:
848
* ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
849
* ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
851
* ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global
852
address space of a compute program.
853
* ``PIPE_BIND_SHADER_BUFFER``: A buffer without a format that can be bound
854
to a shader and can be used with load, store, and atomic instructions.
855
* ``PIPE_BIND_SHADER_IMAGE``: A buffer or texture with a format that can be
856
bound to a shader and can be used with load, store, and atomic instructions.
857
* ``PIPE_BIND_COMPUTE_RESOURCE``: A buffer or texture that can be
858
bound to the compute program as a shader resource.
859
* ``PIPE_BIND_COMMAND_ARGS_BUFFER``: A buffer that may be sourced by the
860
GPU command processor. It can contain, for example, the arguments to
868
The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
869
Note that drivers must always support read and write CPU access at any time
870
no matter which hint they got.
872
* ``PIPE_USAGE_DEFAULT``: Optimized for fast GPU access.
873
* ``PIPE_USAGE_IMMUTABLE``: Optimized for fast GPU access and the resource is
874
not expected to be mapped or changed (even by the GPU) after the first upload.
875
* ``PIPE_USAGE_DYNAMIC``: Expect frequent write-only CPU access. What is
876
uploaded is expected to be used at least several times by the GPU.
877
* ``PIPE_USAGE_STREAM``: Expect frequent write-only CPU access. What is
878
uploaded is expected to be used only once by the GPU.
879
* ``PIPE_USAGE_STAGING``: Optimized for fast CPU access.
890
Returns an identifying name for the screen.
892
The returned string should remain valid and immutable for the lifetime of
898
Returns the screen vendor.
900
The returned string should remain valid and immutable for the lifetime of
906
Returns the actual vendor of the device driving the screen
907
(as opposed to the driver vendor).
909
The returned string should remain valid and immutable for the lifetime of
917
Get an integer/boolean screen parameter.
919
**param** is one of the :ref:`PIPE_CAP` names.
926
Get a floating-point screen parameter.
928
**param** is one of the :ref:`PIPE_CAPF` names.
933
Create a pipe_context.
935
**priv** is private data of the caller, which may be put to various
936
unspecified uses, typically to do with implementing swapbuffers
937
and/or front-buffer rendering.
942
Determine if a resource in the given format can be used in a specific manner.
944
**format** the resource format
946
**target** one of the PIPE_TEXTURE_x flags
948
**sample_count** the number of samples. 0 and 1 mean no multisampling,
949
the maximum allowed legal value is 32.
951
**storage_sample_count** the number of storage samples. This must be <=
952
sample_count. See the documentation of ``pipe_resource::nr_storage_samples``.
954
**bindings** is a bitmask of :ref:`PIPE_BIND` flags.
956
Returns TRUE if all usages can be satisfied.
962
Check if a resource can actually be created (but don't actually allocate any
963
memory). This is used to implement OpenGL's proxy textures. Typically, a
964
driver will simply check if the total size of the given resource is less than
967
For PIPE_TEXTURE_CUBE, the pipe_resource::array_size field should be 6.
975
Create a new resource from a template.
976
The following fields of the pipe_resource must be specified in the template:
978
**target** one of the pipe_texture_target enums.
979
Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
980
Modern APIs allow using buffers as shader resources.
982
**format** one of the pipe_format enums.
984
**width0** the width of the base mip level of the texture or size of the buffer.
986
**height0** the height of the base mip level of the texture
987
(1 for 1D or 1D array textures).
989
**depth0** the depth of the base mip level of the texture
990
(1 for everything else).
992
**array_size** the array size for 1D and 2D array textures.
993
For cube maps this must be 6, for other textures 1.
995
**last_level** the last mip map level present.
997
**nr_samples**: Number of samples determining quality, driving the rasterizer,
998
shading, and framebuffer. It is the number of samples seen by the whole
999
graphics pipeline. 0 and 1 specify a resource which isn't multisampled.
1001
**nr_storage_samples**: Only color buffers can set this lower than nr_samples.
1002
Multiple samples within a pixel can have the same color. ``nr_storage_samples``
1003
determines how many slots for different colors there are per pixel.
1004
If there are not enough slots to store all sample colors, some samples will
1005
have an undefined color (called "undefined samples").
1007
The resolve blit behavior is driver-specific, but can be one of these two:
1009
1. Only defined samples will be averaged. Undefined samples will be ignored.
1010
2. Undefined samples will be approximated by looking at surrounding defined
1011
samples (even in different pixels).
1013
Blits and MSAA texturing: If the sample being fetched is undefined, one of
1014
the defined samples is returned instead.
1016
Sample shading (``set_min_samples``) will operate at a sample frequency that
1017
is at most ``nr_storage_samples``. Greater ``min_samples`` values will be
1018
replaced by ``nr_storage_samples``.
1020
**usage** one of the :ref:`PIPE_USAGE` flags.
1022
**bind** bitmask of the :ref:`PIPE_BIND` flags.
1024
**flags** bitmask of PIPE_RESOURCE_FLAG flags.
1026
**next**: Pointer to the next plane for resources that consist of multiple
1029
As a corollary, this mean resources for an image with multiple planes have
1030
to be created starting from the highest plane.
1035
Mark a resource as changed so derived internal resources will be recreated
1038
When importing external images that can't be directly used as texture sampler
1039
source, internal copies may have to be created that the hardware can sample
1040
from. When those resources are reimported, the image data may have changed, and
1041
the previously derived internal resources must be invalidated to avoid sampling
1049
Destroy a resource. A resource is destroyed if it has no more references.
1056
Query a timestamp in nanoseconds. The returned value should match
1057
PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't
1058
wait for rendering to complete (which cannot be achieved with queries).
1062
get_driver_query_info
1063
^^^^^^^^^^^^^^^^^^^^^
1065
Return a driver-specific query. If the **info** parameter is NULL,
1066
the number of available queries is returned. Otherwise, the driver
1067
query at the specified **index** is returned in **info**.
1068
The function returns non-zero on success.
1069
The driver-specific query is described with the pipe_driver_query_info
1072
get_driver_query_group_info
1073
^^^^^^^^^^^^^^^^^^^^^^^^^^^
1075
Return a driver-specific query group. If the **info** parameter is NULL,
1076
the number of available groups is returned. Otherwise, the driver
1077
query group at the specified **index** is returned in **info**.
1078
The function returns non-zero on success.
1079
The driver-specific query group is described with the
1080
pipe_driver_query_group_info structure.
1084
get_disk_shader_cache
1085
^^^^^^^^^^^^^^^^^^^^^
1087
Returns a pointer to a driver-specific on-disk shader cache. If the driver
1088
failed to create the cache or does not support an on-disk shader cache NULL is
1089
returned. The callback itself may also be NULL if the driver doesn't support
1090
an on-disk shader cache.
1093
is_dmabuf_modifier_supported
1094
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1096
Query whether the driver supports a **modifier** in combination with a
1097
**format**, and whether it is only supported with "external" texture targets.
1098
If the combination is supported in any fashion, true is returned. If the
1099
**external_only** parameter is not NULL, the bool it points to is set to
1100
false if non-external texture targets are supported with the specified modifier+
1101
format, or true if only external texture targets are supported.
1104
get_dmabuf_modifier_planes
1105
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1107
Query the number of planes required by the image layout specified by the
1108
**modifier** and **format** parameters. The value returned includes both planes
1109
dictated by **format** and any additional planes required for driver-specific
1110
auxiliary data necessary for the layout defined by **modifier**.
1111
If the proc is NULL, no auxiliary planes are required for any layout supported by
1112
**screen** and the number of planes can be derived directly from **format**.
1118
Screen methods are required to be thread safe. While gallium rendering
1119
contexts are not required to be thread safe, it is required to be safe to use
1120
different contexts created with the same screen in different threads without
1121
locks. It is also required to be safe using screen methods in a thread, while
1122
using one of its contexts in another (without locks).