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 * ``MAX_TEXTURE_IMAGE_UNITS``: The maximum number of samplers available.
26 * ``NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
27 normalized coordinates, and mipmaps.
28 * ``TWO_SIDED_STENCIL``: Whether the stencil test can also affect back-facing
30 * ``GLSL``: Deprecated.
31 * ``DUAL_SOURCE_BLEND``: Whether dual-source blend factors are supported. See
32 :ref:`Blend` for more information.
33 * ``ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
34 * ``POINT_SPRITE``: Whether point sprites are available.
35 * ``MAX_RENDER_TARGETS``: The maximum number of render targets that may be
37 * ``OCCLUSION_QUERY``: Whether occlusion queries are available.
38 * ``TIMER_QUERY``: Whether timer queries are available.
39 * ``INSTANCED_DRAWING``: indicates support for instanced drawing.
40 * ``TEXTURE_SHADOW_MAP``: indicates whether the fragment shader hardware
41 can do the depth texture / Z comparison operation in TEX instructions
43 * ``MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
45 * ``MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
47 * ``MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
49 * ``TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
51 * ``TEXTURE_MIRROR_REPEAT``: Whether mirrored repeating texture coordinates
53 * ``MAX_VERTEX_TEXTURE_UNITS``: The maximum number of samplers addressable
54 inside the vertex shader. If this is 0, then the vertex shader cannot
56 * ``TGSI_CONT_SUPPORTED``: Whether the TGSI CONT opcode is supported.
57 * ``BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
58 from color blend equations, in :ref:`Blend` state.
59 * ``SM3``: Whether the vertex shader and fragment shader support equivalent
60 opcodes to the Shader Model 3 specification. XXX oh god this is horrible
61 * ``MAX_PREDICATE_REGISTERS``: indicates the number of predicate registers
62 available. Predicate register may be set as a side-effect of ALU
63 instructions to indicate less than, greater than or equal to zero.
64 Later instructions can use a predicate register to control writing to
65 each channel of destination registers. NOTE: predicate registers have
66 not been fully implemented in Gallium at this time. See the
67 GL_NV_fragment_program extension for more info (look for "condition codes").
68 * ``MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
69 the vertex and fragment shader, inclusive.
70 * ``MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
71 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
72 only permit binding one constant buffer per shader, and the shaders will
73 not permit two-dimensional access to constants.
75 If a value greater than 0 is returned, the driver can have multiple
76 constant buffers bound to shader stages. The CONST register file can
77 be accessed with two-dimensional indices, like in the example below.
79 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
80 DCL CONST[3][0] # declare first vector of constbuf 3
81 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
83 For backwards compatibility, one-dimensional access to CONST register
84 file is still supported. In that case, the constbuf index is assumed
87 * ``MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant buffer.
88 * ``INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
89 masks are supported. If 0, then the first rendertarget's blend mask is
90 replicated across all MRTs.
91 * ``INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
92 available. If 0, then the first rendertarget's blend functions affect all
94 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
95 FS_COORD_ORIGIN with value UPPER_LEFT is supported.
96 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
97 FS_COORD_ORIGIN with value LOWER_LEFT is supported.
98 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
99 property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
100 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
101 property FS_COORD_PIXEL_CENTER with value INTEGER is supported.
103 The floating-point capabilities:
105 * ``MAX_LINE_WIDTH``: The maximum width of a regular line.
106 * ``MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
107 * ``MAX_POINT_WIDTH``: The maximum width and height of a point.
108 * ``MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
109 * ``MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
110 applied to anisotropically filtered textures.
111 * ``MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
112 to filtered textures.
113 * ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``,
114 ``GUARD_BAND_BOTTOM``: XXX
116 Fragment shader limits:
118 * ``PIPE_CAP_MAX_FS_INSTRUCTIONS``: The maximum number of instructions.
119 * ``PIPE_CAP_MAX_FS_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
120 * ``PIPE_CAP_MAX_FS_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
121 * ``PIPE_CAP_MAX_FS_TEX_INDIRECTIONS``: The maximum number of texture indirections.
122 * ``PIPE_CAP_MAX_FS_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
123 * ``PIPE_CAP_MAX_FS_INPUTS``: The maximum number of input registers.
124 * ``PIPE_CAP_MAX_FS_CONSTS``: The maximum number of constants.
125 * ``PIPE_CAP_MAX_FS_TEMPS``: The maximum number of temporary registers.
126 * ``PIPE_CAP_MAX_FS_ADDRS``: The maximum number of address registers.
127 * ``PIPE_CAP_MAX_FS_PREDS``: The maximum number of predicate registers.
129 Vertex shader limits:
131 * ``PIPE_CAP_MAX_VS_*``: Identical to ``PIPE_CAP_MAX_FS_*``.
139 These flags indicate how a resource will be used and are specified at resource
140 creation time. Resources may be used in different roles
141 during their lifecycle. Bind flags are cumulative and may be combined to create
142 a resource which can be used for multiple things.
143 Depending on the pipe driver's memory management and these bind flags,
144 resources might be created and handled quite differently.
146 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
147 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs
148 must have this flag set.
149 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
150 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
152 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
153 pipe_screen::flush_front_buffer must have this flag set.
154 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
156 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
157 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
158 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
159 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to.
160 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from.
161 * ``PIPE_BIND_CUSTOM``:
162 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
163 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
171 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
173 * ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws.
174 * ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
175 * ``PIPE_USAGE_STATIC``: Same as immutable (?)
176 * ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload.
177 * ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ...
184 These flags are used when querying whether a particular pipe_format is
185 supported by the driver (with the `is_format_supported` function).
186 Some formats may only be supported for certain kinds of textures.
187 For example, a compressed format might only be used for POT textures.
189 * ``PIPE_TEXTURE_GEOM_NON_SQUARE``: The texture may not be square
190 * ``PIPE_TEXTURE_GEOM_NON_POWER_OF_TWO``: The texture dimensions may not be
202 Returns an identifying name for the screen.
207 Returns the screen vendor.
214 Get an integer/boolean screen parameter.
216 **param** is one of the :ref:`PIPE_CAP` names.
223 Get a floating-point screen parameter.
225 **param** is one of the :ref:`PIPE_CAP` names.
230 Create a pipe_context.
232 **priv** is private data of the caller, which may be put to various
233 unspecified uses, typically to do with implementing swapbuffers
234 and/or front-buffer rendering.
239 Determine if a resource in the given format can be used in a specific manner.
241 **format** the resource format
243 **target** one of the PIPE_TEXTURE_x flags
245 **sample_count** the number of samples. 0 and 1 mean no multisampling,
246 the maximum allowed legal value is 32.
248 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
250 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags.
252 Returns TRUE if all usages can be satisfied.
259 Create a new resource from a template.
260 The following fields of the pipe_resource must be specified in the template:
262 **target** one of the pipe_texture_target enums.
263 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
264 Modern APIs allow using buffers as shader resources.
266 **format** one of the pipe_format enums.
268 **width0** the width of the base mip level of the texture or size of the buffer.
270 **height0** the height of the base mip level of the texture
271 (1 for 1D or 1D array textures).
273 **depth0** the depth of the base mip level of the texture
274 (1 for everything else).
276 **array_size the array size for 1D and 2D array textures.
277 For cube maps this must be 6, for other textures 1.
279 **last_level** the last mip map level present.
281 **nr_samples** the nr of msaa samples. 0 (or 1) specifies a resource
282 which isn't multisampled.
284 **usage** one of the PIPE_USAGE flags.
286 **bind** bitmask of the PIPE_BIND flags.
288 **flags** bitmask of PIPE_RESOURCE_FLAG flags.
295 Destroy a resource. A resource is destroyed if it has no more references.