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_NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
26 normalized coordinates, and mipmaps.
27 * ``PIPE_CAP_TWO_SIDED_STENCIL``: Whether the stencil test can also affect back-facing
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_LEVELS``: The maximum number of mipmap levels available
44 * ``PIPE_CAP_MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
46 * ``PIPE_CAP_MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
48 * ``PIPE_CAP_TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
50 * ``PIPE_CAP_BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
51 from color blend equations, in :ref:`Blend` state.
52 * ``PIPE_CAP_SM3``: Whether the vertex shader and fragment shader support equivalent
53 opcodes to the Shader Model 3 specification. XXX oh god this is horrible
54 * ``PIPE_CAP_MAX_STREAM_OUTPUT_BUFFERS``: The maximum number of stream buffers.
55 * ``PIPE_CAP_PRIMITIVE_RESTART``: Whether primitive restart is supported.
56 * ``PIPE_CAP_MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
57 the vertex and fragment shader, inclusive.
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_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.
71 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
72 property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
73 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
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 (through pipe_rasterizer_state)
77 * ``PIPE_CAP_SHADER_STENCIL_EXPORT``: Whether a stencil reference value can be
78 written from a fragment shader.
79 * ``PIPE_CAP_TGSI_INSTANCEID``: Whether TGSI_SEMANTIC_INSTANCEID is supported
81 * ``PIPE_CAP_VERTEX_ELEMENT_INSTANCE_DIVISOR``: Whether the driver supports
82 per-instance vertex attribs.
83 * ``PIPE_CAP_FRAGMENT_COLOR_CLAMPED``: Whether fragment color clamping is
84 supported. That is, is the pipe_rasterizer_state::clamp_fragment_color
85 flag supported by the driver? If not, the state tracker will insert
86 clamping code into the fragment shaders when needed.
88 * ``PIPE_CAP_MIXED_COLORBUFFER_FORMATS``: Whether mixed colorbuffer formats are
89 supported, e.g. RGBA8 and RGBA32F as the first and second colorbuffer, resp.
90 * ``PIPE_CAP_VERTEX_COLOR_UNCLAMPED``: Whether the driver is capable of
91 outputting unclamped vertex colors from a vertex shader. If unsupported,
92 the vertex colors are always clamped. This is the default for DX9 hardware.
93 * ``PIPE_CAP_VERTEX_COLOR_CLAMPED``: Whether the driver is capable of
94 clamping vertex colors when they come out of a vertex shader, as specified
95 by the pipe_rasterizer_state::clamp_vertex_color flag. If unsupported,
96 the vertex colors are never clamped. This is the default for DX10 hardware.
97 If both clamped and unclamped CAPs are supported, the clamping can be
98 controlled through pipe_rasterizer_state. If the driver cannot do vertex
99 color clamping, the state tracker may insert clamping code into the vertex
101 * ``PIPE_CAP_GLSL_FEATURE_LEVEL``: Whether the driver supports features
102 equivalent to a specific GLSL version. E.g. for GLSL 1.3, report 130.
103 * ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION``: Whether quads adhere to
104 the flatshade_first setting in ``pipe_rasterizer_state``.
105 * ``PIPE_CAP_USER_VERTEX_BUFFERS``: Whether the driver supports user vertex
106 buffers. If not, the state tracker must upload all data which is not in hw
107 resources. If user-space buffers are supported, the driver must also still
108 accept HW resource buffers.
109 * ``PIPE_CAP_VERTEX_BUFFER_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
110 limitation. If true, pipe_vertex_buffer::buffer_offset must always be aligned
111 to 4. If false, there are no restrictions on the offset.
112 * ``PIPE_CAP_VERTEX_BUFFER_STRIDE_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
113 limitation. If true, pipe_vertex_buffer::stride must always be aligned to 4.
114 If false, there are no restrictions on the stride.
115 * ``PIPE_CAP_VERTEX_ELEMENT_SRC_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes
116 a hw limitation. If true, pipe_vertex_element::src_offset must always be
117 aligned to 4. If false, there are no restrictions on src_offset.
118 * ``PIPE_CAP_COMPUTE``: Whether the implementation supports the
119 compute entry points defined in pipe_context and pipe_screen.
120 * ``PIPE_CAP_USER_INDEX_BUFFERS``: Whether user index buffers are supported.
121 If not, the state tracker must upload all indices which are not in hw
122 resources. If user-space buffers are supported, the driver must also still
123 accept HW resource buffers.
124 * ``PIPE_CAP_USER_CONSTANT_BUFFERS``: Whether user-space constant buffers
125 are supported. If not, the state tracker must put constants into HW
126 resources/buffers. If user-space constant buffers are supported, the
127 driver must still accept HW constant buffers also.
128 * ``PIPE_CAP_CONSTANT_BUFFER_OFFSET_ALIGNMENT``: Describes the required
129 alignment of pipe_constant_buffer::buffer_offset.
130 * ``PIPE_CAP_START_INSTANCE``: Whether the driver supports
131 pipe_draw_info::start_instance.
132 * ``PIPE_CAP_QUERY_TIMESTAMP``: Whether PIPE_QUERY_TIMESTAMP and
133 the pipe_screen::get_timestamp hook are implemented.
134 * ``PIPE_CAP_TEXTURE_MULTISAMPLE``: Whether all MSAA resources supported
135 for rendering are also supported for texturing.
136 * ``PIPE_CAP_MIN_MAP_BUFFER_ALIGNMENT``: The minimum alignment that should be
137 expected for a pointer returned by transfer_map if the resource is
138 PIPE_BUFFER. In other words, the pointer returned by transfer_map is
139 always aligned to this value.
140 * ``PIPE_CAP_TEXTURE_BUFFER_OFFSET_ALIGNMENT``: Describes the required
141 alignment for pipe_sampler_view::u.buf.first_element, in bytes.
142 If a driver does not support first/last_element, it should return 0.
143 * ``PIPE_CAP_TGSI_TEXCOORD``: This CAP describes a hw limitation.
144 If true, the hardware cannot replace arbitrary shader inputs with sprite
145 coordinates and hence the inputs that are desired to be replaceable must
146 be declared with TGSI_SEMANTIC_TEXCOORD instead of TGSI_SEMANTIC_GENERIC.
147 The rasterizer's sprite_coord_enable state therefore also applies to the
149 Also, TGSI_SEMANTIC_PCOORD becomes available, which labels a fragment shader
150 input that will always be replaced with sprite coordinates.
151 * ``PIPE_CAP_PREFER_BLIT_BASED_TEXTURE_TRANSFER``: Whether it is preferable
152 to use a blit to implement a texture transfer which needs format conversions
153 and swizzling in state trackers. Generally, all hardware drivers with
154 dedicated memory should return 1 and all software rasterizers should return 0.
155 * ``PIPE_CAP_QUERY_PIPELINE_STATISTICS``: Whether PIPE_QUERY_PIPELINE_STATISTICS
157 * ``PIPE_CAP_TEXTURE_BORDER_COLOR_QUIRK``: Bitmask indicating whether special
158 considerations have to be given to the interaction between the border color
159 in the sampler object and the sampler view used with it.
160 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_R600 is set, the border color
161 may be affected in undefined ways for any kind of permutational swizzle
162 (any swizzle XYZW where X/Y/Z/W are not ZERO, ONE, or R/G/B/A respectively)
164 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_NV50 is set, the border color
165 state should be swizzled manually according to the swizzle in the sampler
166 view it is intended to be used with, or herein undefined results may occur
167 for permutational swizzles.
168 * ``PIPE_CAP_MAX_TEXTURE_BUFFER_SIZE``: The maximum accessible size with
169 a buffer sampler view, in bytes.
170 * ``PIPE_CAP_MAX_VIEWPORTS``: The maximum number of viewports (and scissors
171 since they are linked) a driver can support. Returning 0 is equivalent
172 to returning 1 because every driver has to support at least a single
173 viewport/scissor combination.
174 * ''PIPE_CAP_ENDIANNESS``:: The endianness of the device. Either
175 PIPE_ENDIAN_BIG or PIPE_ENDIAN_LITTLE.
176 * ``PIPE_CAP_MIXED_FRAMEBUFFER_SIZES``: Whether it is allowed to have
177 different sizes for fb color/zs attachments. This controls whether
178 ARB_framebuffer_object is provided.
179 * ``PIPE_CAP_TGSI_VS_LAYER``: Whether TGSI_SEMANTIC_LAYER is supported
180 as a vertex shader output.
188 The floating-point capabilities are:
190 * ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line.
191 * ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
192 * ``PIPE_CAPF_MAX_POINT_WIDTH``: The maximum width and height of a point.
193 * ``PIPE_CAPF_MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
194 * ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
195 applied to anisotropically filtered textures.
196 * ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
197 to filtered textures.
198 * ``PIPE_CAPF_GUARD_BAND_LEFT``,
199 ``PIPE_CAPF_GUARD_BAND_TOP``,
200 ``PIPE_CAPF_GUARD_BAND_RIGHT``,
201 ``PIPE_CAPF_GUARD_BAND_BOTTOM``: TODO
209 These are per-shader-stage capabitity queries. Different shader stages may
210 support different features.
212 * ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions.
213 * ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
214 * ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
215 * ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections.
216 * ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
217 * ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers.
218 * ``PIPE_SHADER_CAP_MAX_CONSTS``: The maximum number of constants.
219 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
220 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
221 only permit binding one constant buffer per shader, and the shaders will
222 not permit two-dimensional access to constants.
224 If a value greater than 0 is returned, the driver can have multiple
225 constant buffers bound to shader stages. The CONST register file can
226 be accessed with two-dimensional indices, like in the example below.
228 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
229 DCL CONST[3][0] # declare first vector of constbuf 3
230 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
232 For backwards compatibility, one-dimensional access to CONST register
233 file is still supported. In that case, the constbuf index is assumed
236 * ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers.
237 * ``PIPE_SHADER_CAP_MAX_ADDRS``: The maximum number of address registers.
238 * ``PIPE_SHADER_CAP_MAX_PREDS``: The maximum number of predicate registers.
239 * ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported.
240 * ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing
241 of the input file is supported.
242 * ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing
243 of the output file is supported.
244 * ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing
245 of the temporary file is supported.
246 * ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing
247 of the constant file is supported.
248 * ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e.
249 BGNSUB, ENDSUB, CAL, and RET, including RET in the main block.
250 * ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported.
251 If unsupported, only float opcodes are supported.
252 * ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: The maximum number of texture
254 * ``PIPE_SHADER_CAP_PREFERRED_IR``: Preferred representation of the
255 program. It should be one of the ``pipe_shader_ir`` enum values.
256 * ``PIPE_SHADER_CAP_MAX_SAMPLER_VIEWS``: The maximum number of texture
257 sampler views. Must not be lower than PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS.
260 .. _pipe_compute_cap:
265 Compute-specific capabilities. They can be queried using
266 pipe_screen::get_compute_param.
268 * ``PIPE_COMPUTE_CAP_IR_TARGET``: A description of the target of the form
269 ``processor-arch-manufacturer-os`` that will be passed on to the compiler.
270 This CAP is only relevant for drivers that specify PIPE_SHADER_IR_LLVM for
272 Value type: null-terminated string.
273 * ``PIPE_COMPUTE_CAP_GRID_DIMENSION``: Number of supported dimensions
274 for grid and block coordinates. Value type: ``uint64_t``.
275 * ``PIPE_COMPUTE_CAP_MAX_GRID_SIZE``: Maximum grid size in block
276 units. Value type: ``uint64_t []``.
277 * ``PIPE_COMPUTE_CAP_MAX_BLOCK_SIZE``: Maximum block size in thread
278 units. Value type: ``uint64_t []``.
279 * ``PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK``: Maximum number of threads that
280 a single block can contain. Value type: ``uint64_t``.
281 This may be less than the product of the components of MAX_BLOCK_SIZE and is
282 usually limited by the number of threads that can be resident simultaneously
284 * ``PIPE_COMPUTE_CAP_MAX_GLOBAL_SIZE``: Maximum size of the GLOBAL
285 resource. Value type: ``uint64_t``.
286 * ``PIPE_COMPUTE_CAP_MAX_LOCAL_SIZE``: Maximum size of the LOCAL
287 resource. Value type: ``uint64_t``.
288 * ``PIPE_COMPUTE_CAP_MAX_PRIVATE_SIZE``: Maximum size of the PRIVATE
289 resource. Value type: ``uint64_t``.
290 * ``PIPE_COMPUTE_CAP_MAX_INPUT_SIZE``: Maximum size of the INPUT
291 resource. Value type: ``uint64_t``.
292 * ``PIPE_COMPUTE_CAP_MAX_MEM_ALLOC_SIZE``: Maximum size of a memory object
293 allocation in bytes. Value type: ``uint64_t``.
300 These flags indicate how a resource will be used and are specified at resource
301 creation time. Resources may be used in different roles
302 during their lifecycle. Bind flags are cumulative and may be combined to create
303 a resource which can be used for multiple things.
304 Depending on the pipe driver's memory management and these bind flags,
305 resources might be created and handled quite differently.
307 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
308 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs
309 must have this flag set.
310 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
311 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
313 * ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to
314 query whether a device supports blending for a given format.
315 If this flag is set, surface creation may fail if blending is not supported
316 for the specified format. If it is not set, a driver may choose to ignore
317 blending on surfaces with formats that would require emulation.
318 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
319 pipe_screen::flush_front_buffer must have this flag set.
320 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
322 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
323 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
324 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
325 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to.
326 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from.
327 * ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer.
328 * ``PIPE_BIND_CUSTOM``:
329 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
330 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
332 * ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global
333 address space of a compute program.
334 * ``PIPE_BIND_SHADER_RESOURCE``: A buffer or texture that can be
335 bound to the graphics pipeline as a shader resource.
336 * ``PIPE_BIND_COMPUTE_RESOURCE``: A buffer or texture that can be
337 bound to the compute program as a shader resource.
344 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
346 * ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws.
347 * ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
348 * ``PIPE_USAGE_STATIC``: Same as immutable (?)
349 * ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload.
350 * ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ...
361 Returns an identifying name for the screen.
366 Returns the screen vendor.
373 Get an integer/boolean screen parameter.
375 **param** is one of the :ref:`PIPE_CAP` names.
382 Get a floating-point screen parameter.
384 **param** is one of the :ref:`PIPE_CAP` names.
389 Create a pipe_context.
391 **priv** is private data of the caller, which may be put to various
392 unspecified uses, typically to do with implementing swapbuffers
393 and/or front-buffer rendering.
398 Determine if a resource in the given format can be used in a specific manner.
400 **format** the resource format
402 **target** one of the PIPE_TEXTURE_x flags
404 **sample_count** the number of samples. 0 and 1 mean no multisampling,
405 the maximum allowed legal value is 32.
407 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
409 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags.
411 Returns TRUE if all usages can be satisfied.
417 Check if a resource can actually be created (but don't actually allocate any
418 memory). This is used to implement OpenGL's proxy textures. Typically, a
419 driver will simply check if the total size of the given resource is less than
428 Create a new resource from a template.
429 The following fields of the pipe_resource must be specified in the template:
431 **target** one of the pipe_texture_target enums.
432 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
433 Modern APIs allow using buffers as shader resources.
435 **format** one of the pipe_format enums.
437 **width0** the width of the base mip level of the texture or size of the buffer.
439 **height0** the height of the base mip level of the texture
440 (1 for 1D or 1D array textures).
442 **depth0** the depth of the base mip level of the texture
443 (1 for everything else).
445 **array_size** the array size for 1D and 2D array textures.
446 For cube maps this must be 6, for other textures 1.
448 **last_level** the last mip map level present.
450 **nr_samples** the nr of msaa samples. 0 (or 1) specifies a resource
451 which isn't multisampled.
453 **usage** one of the PIPE_USAGE flags.
455 **bind** bitmask of the PIPE_BIND flags.
457 **flags** bitmask of PIPE_RESOURCE_FLAG flags.
464 Destroy a resource. A resource is destroyed if it has no more references.
471 Query a timestamp in nanoseconds. The returned value should match
472 PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't
473 wait for rendering to complete (which cannot be achieved with queries).
477 get_driver_query_info
478 ^^^^^^^^^^^^^^^^^^^^^
480 Return a driver-specific query. If the **info** parameter is NULL,
481 the number of available queries is returned. Otherwise, the driver
482 query at the specified **index** is returned in **info**.
483 The function returns non-zero on success.
484 The driver-specific query is described with the pipe_driver_query_info