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_TIMER_QUERY``: Whether timer 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_DEPTHSTENCIL_CLEAR_SEPARATE``: Whether clearing only depth or only
65 stencil in a combined depth-stencil buffer is supported.
66 * ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS``: The maximum number of texture array
67 layers supported. If 0, the array textures are not supported at all and
68 the ARRAY texture targets are invalid.
69 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
70 FS_COORD_ORIGIN with value UPPER_LEFT is supported.
71 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
72 FS_COORD_ORIGIN with value LOWER_LEFT is supported.
73 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
74 property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
75 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
76 property FS_COORD_PIXEL_CENTER with value INTEGER is supported.
77 * ``PIPE_CAP_DEPTH_CLIP_DISABLE``: Whether the driver is capable of disabling
78 depth clipping (through pipe_rasterizer_state)
79 * ``PIPE_CAP_SHADER_STENCIL_EXPORT``: Whether a stencil reference value can be
80 written from a fragment shader.
81 * ``PIPE_CAP_TGSI_INSTANCEID``: Whether TGSI_SEMANTIC_INSTANCEID is supported
83 * ``PIPE_CAP_VERTEX_ELEMENT_INSTANCE_DIVISOR``: Whether the driver supports
84 per-instance vertex attribs.
85 * ``PIPE_CAP_FRAGMENT_COLOR_CLAMPED``: Whether fragment color clamping is
87 * ``PIPE_CAP_MIXED_COLORBUFFER_FORMATS``: Whether mixed colorbuffer formats are
88 supported, e.g. RGBA8 and RGBA32F as the first and second colorbuffer, resp.
89 * ``PIPE_CAP_VERTEX_COLOR_UNCLAMPED``: Whether the driver is capable of
90 outputting unclamped vertex colors from a vertex shader. If unsupported,
91 the vertex colors are always clamped. This is the default for DX9 hardware.
92 * ``PIPE_CAP_VERTEX_COLOR_CLAMPED``: Whether the driver is capable of
93 clamping vertex colors when they come out of a vertex shader. If unsupported,
94 the vertex colors are never clamped. This is the default for DX10 hardware.
95 If both clamped and unclamped CAPs are supported, the clamping can be
96 controlled through pipe_rasterizer_state.
97 * ``PIPE_CAP_GLSL_FEATURE_LEVEL``: Whether the driver supports features
98 equivalent to a specific GLSL version. E.g. for GLSL 1.3, report 130.
99 * ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION``: Whether quads adhere to
100 the flatshade_first setting in ``pipe_rasterizer_state``.
101 * ``PIPE_CAP_USER_VERTEX_BUFFERS``: Whether the driver supports user vertex
102 buffers. If not, the state tracker must upload all data which is not in hw
104 * ``PIPE_CAP_VERTEX_BUFFER_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
105 limitation. If true, pipe_vertex_buffer::buffer_offset must always be aligned
106 to 4. If false, there are no restrictions on the offset.
107 * ``PIPE_CAP_VERTEX_BUFFER_STRIDE_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
108 limitation. If true, pipe_vertex_buffer::stride must always be aligned to 4.
109 If false, there are no restrictions on the stride.
110 * ``PIPE_CAP_VERTEX_ELEMENT_SRC_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes
111 a hw limitation. If true, pipe_vertex_element::src_offset must always be
112 aligned to 4. If false, there are no restrictions on src_offset.
113 * ``PIPE_CAP_COMPUTE``: Whether the implementation supports the
114 compute entry points defined in pipe_context and pipe_screen.
122 The floating-point capabilities are:
124 * ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line.
125 * ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
126 * ``PIPE_CAPF_MAX_POINT_WIDTH``: The maximum width and height of a point.
127 * ``PIPE_CAPF_MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
128 * ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
129 applied to anisotropically filtered textures.
130 * ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
131 to filtered textures.
132 * ``PIPE_CAPF_GUARD_BAND_LEFT``,
133 ``PIPE_CAPF_GUARD_BAND_TOP``,
134 ``PIPE_CAPF_GUARD_BAND_RIGHT``,
135 ``PIPE_CAPF_GUARD_BAND_BOTTOM``: TODO
143 These are per-shader-stage capabitity queries. Different shader stages may
144 support different features.
146 * ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions.
147 * ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
148 * ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
149 * ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections.
150 * ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
151 * ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers.
152 * ``PIPE_SHADER_CAP_MAX_CONSTS``: The maximum number of constants.
153 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
154 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
155 only permit binding one constant buffer per shader, and the shaders will
156 not permit two-dimensional access to constants.
158 If a value greater than 0 is returned, the driver can have multiple
159 constant buffers bound to shader stages. The CONST register file can
160 be accessed with two-dimensional indices, like in the example below.
162 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
163 DCL CONST[3][0] # declare first vector of constbuf 3
164 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
166 For backwards compatibility, one-dimensional access to CONST register
167 file is still supported. In that case, the constbuf index is assumed
170 * ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers.
171 * ``PIPE_SHADER_CAP_MAX_ADDRS``: The maximum number of address registers.
172 * ``PIPE_SHADER_CAP_MAX_PREDS``: The maximum number of predicate registers.
173 * ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported.
174 * ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing
175 of the input file is supported.
176 * ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing
177 of the output file is supported.
178 * ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing
179 of the temporary file is supported.
180 * ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing
181 of the constant file is supported.
182 * ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e.
183 BGNSUB, ENDSUB, CAL, and RET, including RET in the main block.
184 * ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported.
185 If unsupported, only float opcodes are supported.
186 * ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: THe maximum number of texture
188 * ``PIPE_SHADER_CAP_PREFERRED_IR``: Preferred representation of the
189 program. It should be one of the ``pipe_shader_ir`` enum values.
192 .. _pipe_compute_cap:
197 Compute-specific capabilities. They can be queried using
198 pipe_screen::get_compute_param.
200 * ``PIPE_COMPUTE_CAP_GRID_DIMENSION``: Number of supported dimensions
201 for grid and block coordinates. Value type: ``uint64_t``.
202 * ``PIPE_COMPUTE_CAP_MAX_GRID_SIZE``: Maximum grid size in block
203 units. Value type: ``uint64_t []``.
204 * ``PIPE_COMPUTE_CAP_MAX_BLOCK_SIZE``: Maximum block size in thread
205 units. Value type: ``uint64_t []``.
206 * ``PIPE_COMPUTE_CAP_MAX_GLOBAL_SIZE``: Maximum size of the GLOBAL
207 resource. Value type: ``uint64_t``.
208 * ``PIPE_COMPUTE_CAP_MAX_LOCAL_SIZE``: Maximum size of the LOCAL
209 resource. Value type: ``uint64_t``.
210 * ``PIPE_COMPUTE_CAP_MAX_PRIVATE_SIZE``: Maximum size of the PRIVATE
211 resource. Value type: ``uint64_t``.
212 * ``PIPE_COMPUTE_CAP_MAX_INPUT_SIZE``: Maximum size of the INPUT
213 resource. Value type: ``uint64_t``.
220 These flags indicate how a resource will be used and are specified at resource
221 creation time. Resources may be used in different roles
222 during their lifecycle. Bind flags are cumulative and may be combined to create
223 a resource which can be used for multiple things.
224 Depending on the pipe driver's memory management and these bind flags,
225 resources might be created and handled quite differently.
227 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
228 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs
229 must have this flag set.
230 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
231 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
233 * ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to
234 query whether a device supports blending for a given format.
235 If this flag is set, surface creation may fail if blending is not supported
236 for the specified format. If it is not set, a driver may choose to ignore
237 blending on surfaces with formats that would require emulation.
238 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
239 pipe_screen::flush_front_buffer must have this flag set.
240 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
242 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
243 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
244 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
245 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to.
246 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from.
247 * ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer.
248 * ``PIPE_BIND_CUSTOM``:
249 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
250 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
252 * ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global
253 address space of a compute program.
254 * ``PIPE_BIND_SHADER_RESOURCE``: A buffer or texture that can be
255 bound to the graphics pipeline as a shader resource.
256 * ``PIPE_BIND_COMPUTE_RESOURCE``: A buffer or texture that can be
257 bound to the compute program as a shader resource.
264 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
266 * ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws.
267 * ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
268 * ``PIPE_USAGE_STATIC``: Same as immutable (?)
269 * ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload.
270 * ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ...
281 Returns an identifying name for the screen.
286 Returns the screen vendor.
293 Get an integer/boolean screen parameter.
295 **param** is one of the :ref:`PIPE_CAP` names.
302 Get a floating-point screen parameter.
304 **param** is one of the :ref:`PIPE_CAP` names.
309 Create a pipe_context.
311 **priv** is private data of the caller, which may be put to various
312 unspecified uses, typically to do with implementing swapbuffers
313 and/or front-buffer rendering.
318 Determine if a resource in the given format can be used in a specific manner.
320 **format** the resource format
322 **target** one of the PIPE_TEXTURE_x flags
324 **sample_count** the number of samples. 0 and 1 mean no multisampling,
325 the maximum allowed legal value is 32.
327 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
329 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags.
331 Returns TRUE if all usages can be satisfied.
338 Create a new resource from a template.
339 The following fields of the pipe_resource must be specified in the template:
341 **target** one of the pipe_texture_target enums.
342 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
343 Modern APIs allow using buffers as shader resources.
345 **format** one of the pipe_format enums.
347 **width0** the width of the base mip level of the texture or size of the buffer.
349 **height0** the height of the base mip level of the texture
350 (1 for 1D or 1D array textures).
352 **depth0** the depth of the base mip level of the texture
353 (1 for everything else).
355 **array_size** the array size for 1D and 2D array textures.
356 For cube maps this must be 6, for other textures 1.
358 **last_level** the last mip map level present.
360 **nr_samples** the nr of msaa samples. 0 (or 1) specifies a resource
361 which isn't multisampled.
363 **usage** one of the PIPE_USAGE flags.
365 **bind** bitmask of the PIPE_BIND flags.
367 **flags** bitmask of PIPE_RESOURCE_FLAG flags.
374 Destroy a resource. A resource is destroyed if it has no more references.