4 A screen is an object representing the context-independent part of a device.
9 XXX some of these don't belong in this section.
17 Capability queries return information about the features and limits of the
18 driver/GPU. For floating-point values, use :ref:`get_paramf`, and for boolean
19 or integer values, use :ref:`get_param`.
21 The integer capabilities:
23 * ``MAX_TEXTURE_IMAGE_UNITS``: The maximum number of samplers available.
24 * ``NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
25 normalized coordinates, and mipmaps.
26 * ``TWO_SIDED_STENCIL``: Whether the stencil test can also affect back-facing
28 * ``GLSL``: Deprecated.
29 * ``DUAL_SOURCE_BLEND``: Whether dual-source blend factors are supported. See
30 :ref:`Blend` for more information.
31 * ``ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
32 * ``POINT_SPRITE``: Whether point sprites are available.
33 * ``MAX_RENDER_TARGETS``: The maximum number of render targets that may be
35 * ``OCCLUSION_QUERY``: Whether occlusion queries are available.
36 * ``TEXTURE_SHADOW_MAP``: XXX
37 * ``MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
39 * ``MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
41 * ``MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
43 * ``TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
45 * ``TEXTURE_MIRROR_REPEAT``: Whether mirrored repeating texture coordinates
47 * ``MAX_VERTEX_TEXTURE_UNITS``: The maximum number of samplers addressable
48 inside the vertex shader. If this is 0, then the vertex shader cannot
50 * ``TGSI_CONT_SUPPORTED``: Whether the TGSI CONT opcode is supported.
51 * ``BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
52 from color blend equations, in :ref:`Blend` state.
53 * ``SM3``: Whether the vertex shader and fragment shader support equivalent
54 opcodes to the Shader Model 3 specification. XXX oh god this is horrible
55 * ``MAX_PREDICATE_REGISTERS``: XXX
56 * ``MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
57 the vertex and fragment shader, inclusive.
58 * ``MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
59 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
60 only permit binding one constant buffer per shader, and the shaders will
61 not permit two-dimensional access to constants.
63 If a value greater than 0 is returned, the driver can have multiple
64 constant buffers bound to shader stages. The CONST register file can
65 be accessed with two-dimensional indices, like in the example below.
67 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
68 DCL CONST[3][0] # declare first vector of constbuf 3
69 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
71 For backwards compatibility, one-dimensional access to CONST register
72 file is still supported. In that case, the constbuf index is assumed
75 * ``MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant buffer.
76 * ``INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
77 masks are supported. If 0, then the first rendertarget's blend mask is
78 replicated across all MRTs.
79 * ``INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
80 available. If 0, then the first rendertarget's blend functions affect all
82 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
83 FS_COORD_ORIGIN with value UPPER_LEFT is supported.
84 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
85 FS_COORD_ORIGIN with value LOWER_LEFT is supported.
86 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
87 property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
88 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
89 property FS_COORD_PIXEL_CENTER with value INTEGER is supported.
91 The floating-point capabilities:
93 * ``MAX_LINE_WIDTH``: The maximum width of a regular line.
94 * ``MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
95 * ``MAX_POINT_WIDTH``: The maximum width and height of a point.
96 * ``MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
97 * ``MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
98 applied to anisotropically filtered textures.
99 * ``MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
100 to filtered textures.
101 * ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``,
102 ``GUARD_BAND_BOTTOM``: XXX
111 These flags indicate how a resource will be used and are specified at resource
112 creation time. Resources may be used in different roles
113 during their lifecycle. Bind flags are cumulative and may be combined to create
114 a resource which can be used for multiple things.
115 Depending on the pipe driver's memory management and these bind flags,
116 resources might be created and handled quite differently.
118 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
119 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs
120 must have this flag set.
121 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
122 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
124 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
125 pipe_screen::flush_front_buffer must have this flag set.
126 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
128 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
129 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
130 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
131 * ``PIPE_BIND_BLIT_SOURCE``: A blit source, as given to surface_copy.
132 * ``PIPE_BIND_BLIT_DESTINATION``: A blit destination, as given to surface_copy
134 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to.
135 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from.
136 * ``PIPE_BIND_CUSTOM``:
137 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
138 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
146 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
148 * ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws.
149 * ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
150 * ``PIPE_USAGE_STATIC``: Same as immutable (?)
151 * ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload.
152 * ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ...
159 These flags are used when querying whether a particular pipe_format is
160 supported by the driver (with the `is_format_supported` function).
161 Some formats may only be supported for certain kinds of textures.
162 For example, a compressed format might only be used for POT textures.
164 * ``PIPE_TEXTURE_GEOM_NON_SQUARE``: The texture may not be square
165 * ``PIPE_TEXTURE_GEOM_NON_POWER_OF_TWO``: The texture dimensions may not be
177 Returns an identifying name for the screen.
182 Returns the screen vendor.
189 Get an integer/boolean screen parameter.
191 **param** is one of the :ref:`PIPE_CAP` names.
198 Get a floating-point screen parameter.
200 **param** is one of the :ref:`PIPE_CAP` names.
205 Create a pipe_context.
207 **priv** is private data of the caller, which may be put to various
208 unspecified uses, typically to do with implementing swapbuffers
209 and/or front-buffer rendering.
214 Determine if a resource in the given format can be used in a specific manner.
216 **format** the resource format
218 **target** one of the PIPE_TEXTURE_x flags
220 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
222 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags.
224 Returns TRUE if all usages can be satisfied.
232 Create a new resource from a template.
233 The following fields of the pipe_resource must be specified in the template:
260 Destroy a resource. A resource is destroyed if it has no more references.