4 A screen is an object representing the context-independent part of a device.
14 Pipe capabilities help expose hardware functionality not explicitly required
15 by Gallium. For floating-point values, use :ref:`get_paramf`, and for boolean
16 or integer values, use :ref:`get_param`.
18 The integer capabilities:
20 * ``MAX_TEXTURE_IMAGE_UNITS``: The maximum number of samplers available.
21 * ``NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
22 normalized coordinates, and mipmaps.
23 * ``TWO_SIDED_STENCIL``: Whether the stencil test can also affect back-facing
25 * ``GLSL``: Deprecated.
26 * ``DUAL_SOURCE_BLEND``: Whether dual-source blend factors are supported. See
27 :ref:`Blend` for more information.
28 * ``ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
29 * ``POINT_SPRITE``: Whether point sprites are available.
30 * ``MAX_RENDER_TARGETS``: The maximum number of render targets that may be
32 * ``OCCLUSION_QUERY``: Whether occlusion queries are available.
33 * ``TEXTURE_SHADOW_MAP``: XXX
34 * ``MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
36 * ``MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
38 * ``MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
40 * ``TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
42 * ``TEXTURE_MIRROR_REPEAT``: Whether mirrored repeating texture coordinates
44 * ``MAX_VERTEX_TEXTURE_UNITS``: The maximum number of samplers addressable
45 inside the vertex shader. If this is 0, then the vertex shader cannot
47 * ``TGSI_CONT_SUPPORTED``: Whether the TGSI CONT opcode is supported.
48 * ``BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
49 from color blend equations, in :ref:`Blend` state.
50 * ``SM3``: Whether the vertex shader and fragment shader support equivalent
51 opcodes to the Shader Model 3 specification. XXX oh god this is horrible
52 * ``MAX_PREDICATE_REGISTERS``: XXX
53 * ``MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
54 the vertex and fragment shader, inclusive.
55 * ``MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
56 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
57 only permit binding one constant buffer per shader, and the shaders will
58 not permit two-dimensional access to constants.
59 * ``MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant buffer.
60 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
61 FS_COORD_ORIGIN with value UPPER_LEFT is supported
62 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
63 FS_COORD_ORIGIN with value LOWER_LEFT is supported
64 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
65 property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported
66 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
67 property FS_COORD_PIXEL_CENTER with value INTEGER is supported
69 The floating-point capabilities:
71 * ``MAX_LINE_WIDTH``: The maximum width of a regular line.
72 * ``MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
73 * ``MAX_POINT_WIDTH``: The maximum width and height of a point.
74 * ``MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
75 * ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``,
76 ``GUARD_BAND_BOTTOM``: XXX
78 XXX Is there a better home for this? vvv
80 If 0 is returned, the driver is not aware of multiple constant buffers,
81 supports binding of only one constant buffer, and does not support
82 two-dimensional CONST register file access in TGSI shaders.
84 If a value greater than 0 is returned, the driver can have multiple
85 constant buffers bound to shader stages. The CONST register file can
86 be accessed with two-dimensional indices, like in the example below.
88 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
89 DCL CONST[3][0] # declare first vector of constbuf 3
90 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
92 For backwards compatibility, one-dimensional access to CONST register
93 file is still supported. In that case, the constbuf index is assumed
96 .. _pipe_buffer_usage:
101 These flags control buffer creation. Buffers may only have one role, so
102 care should be taken to not allocate a buffer with the wrong usage.
104 * ``PIXEL``: This is the flag to use for all textures.
105 * ``VERTEX``: A vertex buffer.
106 * ``INDEX``: An element buffer.
107 * ``CONSTANT``: A buffer of shader constants.
109 Buffers are inevitably abstracting the pipe's underlying memory management,
110 so many of their usage flags can be used to direct the way the buffer is
113 * ``CPU_READ``, ``CPU_WRITE``: Whether the user will map and, in the case of
114 the latter, write to, the buffer. The convenience flag ``CPU_READ_WRITE`` is
115 available to signify a read/write buffer.
116 * ``GPU_READ``, ``GPU_WRITE``: Whether the driver will internally need to
117 read from or write to the buffer. The latter will only happen if the buffer
118 is made into a render target.
119 * ``DISCARD``: When set on a map, the contents of the map will be discarded
120 beforehand. Cannot be used with ``CPU_READ``.
121 * ``DONTBLOCK``: When set on a map, the map will fail if the buffer cannot be
123 * ``UNSYNCHRONIZED``: When set on a map, any outstanding operations on the
124 buffer will be ignored. The interaction of any writes to the map and any
125 operations pending with the buffer are undefined. Cannot be used with
127 * ``FLUSH_EXPLICIT``: When set on a map, written ranges of the map require
128 explicit flushes using :ref:`buffer_flush_mapped_range`. Requires
131 .. _pipe_texture_usage:
136 These flags determine the possible roles a texture may be used for during its
137 lifetime. Texture usage flags are cumulative and may be combined to create a
138 texture that can be used as multiple things.
140 * ``RENDER_TARGET``: A colorbuffer or pixelbuffer.
141 * ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
142 * ``PRIMARY``: A frontbuffer or scanout buffer.
143 * ``DEPTH_STENCIL``: A depthbuffer, stencilbuffer, or Z buffer. Gallium does
144 not explicitly provide for stencil-only buffers, so any stencilbuffer
145 validated here is implicitly also a depthbuffer.
146 * ``SAMPLER``: A texture that may be sampled from in a fragment or vertex
148 * ``DYNAMIC``: A texture that will be mapped frequently.
158 Returns an identifying name for the screen.
163 Returns the screen vendor.
170 Get an integer/boolean screen parameter.
172 **param** is one of the :ref:`PIPE_CAP` names.
179 Get a floating-point screen parameter.
181 **param** is one of the :ref:`PIPE_CAP` names.
186 See if a format can be used in a specific manner.
188 **usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
190 Returns TRUE if all usages can be satisfied.
194 ``PIPE_TEXTURE_USAGE_DYNAMIC`` is not a valid usage.
201 Given a template of texture setup, create a buffer and texture.
206 Like :ref:`texture_create`, but use a supplied buffer instead of creating a
212 Destroy a texture. The buffer backing the texture is destroyed if it has no
218 Map a buffer into memory.
220 **usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
222 Returns a pointer to the map, or NULL if the mapping failed.
227 Map a range of a buffer into memory.
229 The returned map is always relative to the beginning of the buffer, not the
230 beginning of the mapped range.
232 .. _buffer_flush_mapped_range:
234 buffer_flush_mapped_range
235 ^^^^^^^^^^^^^^^^^^^^^^^^^
237 Flush a range of mapped memory into a buffer.
239 The buffer must have been mapped with ``PIPE_BUFFER_USAGE_FLUSH_EXPLICIT``.
241 **usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
246 Unmap a buffer from memory.
248 Any pointers into the map should be considered invalid and discarded.