gallium: rename PIPE_CAP_TGSI_VS_LAYER to also have _VIEWPORT
[mesa.git] / src / gallium / docs / source / screen.rst
1 .. _screen:
2
3 Screen
4 ======
5
6 A screen is an object representing the context-independent part of a device.
7
8 Flags and enumerations
9 ----------------------
10
11 XXX some of these don't belong in this section.
12
13
14 .. _pipe_cap:
15
16 PIPE_CAP_*
17 ^^^^^^^^^^
18
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`.
22
23 The integer capabilities:
24
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
28 polygons.
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
34 bound.
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
39 for shadow testing.
40 * ``PIPE_CAP_TEXTURE_SWIZZLE``: Whether swizzling through sampler views is
41 supported.
42 * ``PIPE_CAP_MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
43 for a 2D texture.
44 * ``PIPE_CAP_MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
45 for a 3D texture.
46 * ``PIPE_CAP_MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
47 for a cubemap.
48 * ``PIPE_CAP_TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
49 are supported.
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_INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
57 masks are supported. If 0, then the first rendertarget's blend mask is
58 replicated across all MRTs.
59 * ``PIPE_CAP_INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
60 available. If 0, then the first rendertarget's blend functions affect all
61 MRTs.
62 * ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS``: The maximum number of texture array
63 layers supported. If 0, the array textures are not supported at all and
64 the ARRAY texture targets are invalid.
65 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
66 FS_COORD_ORIGIN with value UPPER_LEFT is supported.
67 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
68 FS_COORD_ORIGIN with value LOWER_LEFT is supported.
69 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
70 property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
71 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
72 property FS_COORD_PIXEL_CENTER with value INTEGER is supported.
73 * ``PIPE_CAP_DEPTH_CLIP_DISABLE``: Whether the driver is capable of disabling
74 depth clipping (through pipe_rasterizer_state)
75 * ``PIPE_CAP_SHADER_STENCIL_EXPORT``: Whether a stencil reference value can be
76 written from a fragment shader.
77 * ``PIPE_CAP_TGSI_INSTANCEID``: Whether TGSI_SEMANTIC_INSTANCEID is supported
78 in the vertex shader.
79 * ``PIPE_CAP_VERTEX_ELEMENT_INSTANCE_DIVISOR``: Whether the driver supports
80 per-instance vertex attribs.
81 * ``PIPE_CAP_FRAGMENT_COLOR_CLAMPED``: Whether fragment color clamping is
82 supported. That is, is the pipe_rasterizer_state::clamp_fragment_color
83 flag supported by the driver? If not, the state tracker will insert
84 clamping code into the fragment shaders when needed.
85
86 * ``PIPE_CAP_MIXED_COLORBUFFER_FORMATS``: Whether mixed colorbuffer formats are
87 supported, e.g. RGBA8 and RGBA32F as the first and second colorbuffer, resp.
88 * ``PIPE_CAP_VERTEX_COLOR_UNCLAMPED``: Whether the driver is capable of
89 outputting unclamped vertex colors from a vertex shader. If unsupported,
90 the vertex colors are always clamped. This is the default for DX9 hardware.
91 * ``PIPE_CAP_VERTEX_COLOR_CLAMPED``: Whether the driver is capable of
92 clamping vertex colors when they come out of a vertex shader, as specified
93 by the pipe_rasterizer_state::clamp_vertex_color flag. 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. If the driver cannot do vertex
97 color clamping, the state tracker may insert clamping code into the vertex
98 shader.
99 * ``PIPE_CAP_GLSL_FEATURE_LEVEL``: Whether the driver supports features
100 equivalent to a specific GLSL version. E.g. for GLSL 1.3, report 130.
101 * ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION``: Whether quads adhere to
102 the flatshade_first setting in ``pipe_rasterizer_state``.
103 * ``PIPE_CAP_USER_VERTEX_BUFFERS``: Whether the driver supports user vertex
104 buffers. If not, the state tracker must upload all data which is not in hw
105 resources. If user-space buffers are supported, the driver must also still
106 accept HW resource buffers.
107 * ``PIPE_CAP_VERTEX_BUFFER_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
108 limitation. If true, pipe_vertex_buffer::buffer_offset must always be aligned
109 to 4. If false, there are no restrictions on the offset.
110 * ``PIPE_CAP_VERTEX_BUFFER_STRIDE_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
111 limitation. If true, pipe_vertex_buffer::stride must always be aligned to 4.
112 If false, there are no restrictions on the stride.
113 * ``PIPE_CAP_VERTEX_ELEMENT_SRC_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes
114 a hw limitation. If true, pipe_vertex_element::src_offset must always be
115 aligned to 4. If false, there are no restrictions on src_offset.
116 * ``PIPE_CAP_COMPUTE``: Whether the implementation supports the
117 compute entry points defined in pipe_context and pipe_screen.
118 * ``PIPE_CAP_USER_INDEX_BUFFERS``: Whether user index buffers are supported.
119 If not, the state tracker must upload all indices which are not in hw
120 resources. If user-space buffers are supported, the driver must also still
121 accept HW resource buffers.
122 * ``PIPE_CAP_USER_CONSTANT_BUFFERS``: Whether user-space constant buffers
123 are supported. If not, the state tracker must put constants into HW
124 resources/buffers. If user-space constant buffers are supported, the
125 driver must still accept HW constant buffers also.
126 * ``PIPE_CAP_CONSTANT_BUFFER_OFFSET_ALIGNMENT``: Describes the required
127 alignment of pipe_constant_buffer::buffer_offset.
128 * ``PIPE_CAP_START_INSTANCE``: Whether the driver supports
129 pipe_draw_info::start_instance.
130 * ``PIPE_CAP_QUERY_TIMESTAMP``: Whether PIPE_QUERY_TIMESTAMP and
131 the pipe_screen::get_timestamp hook are implemented.
132 * ``PIPE_CAP_TEXTURE_MULTISAMPLE``: Whether all MSAA resources supported
133 for rendering are also supported for texturing.
134 * ``PIPE_CAP_MIN_MAP_BUFFER_ALIGNMENT``: The minimum alignment that should be
135 expected for a pointer returned by transfer_map if the resource is
136 PIPE_BUFFER. In other words, the pointer returned by transfer_map is
137 always aligned to this value.
138 * ``PIPE_CAP_TEXTURE_BUFFER_OFFSET_ALIGNMENT``: Describes the required
139 alignment for pipe_sampler_view::u.buf.first_element, in bytes.
140 If a driver does not support first/last_element, it should return 0.
141 * ``PIPE_CAP_TGSI_TEXCOORD``: This CAP describes a hw limitation.
142 If true, the hardware cannot replace arbitrary shader inputs with sprite
143 coordinates and hence the inputs that are desired to be replaceable must
144 be declared with TGSI_SEMANTIC_TEXCOORD instead of TGSI_SEMANTIC_GENERIC.
145 The rasterizer's sprite_coord_enable state therefore also applies to the
146 TEXCOORD semantic.
147 Also, TGSI_SEMANTIC_PCOORD becomes available, which labels a fragment shader
148 input that will always be replaced with sprite coordinates.
149 * ``PIPE_CAP_PREFER_BLIT_BASED_TEXTURE_TRANSFER``: Whether it is preferable
150 to use a blit to implement a texture transfer which needs format conversions
151 and swizzling in state trackers. Generally, all hardware drivers with
152 dedicated memory should return 1 and all software rasterizers should return 0.
153 * ``PIPE_CAP_QUERY_PIPELINE_STATISTICS``: Whether PIPE_QUERY_PIPELINE_STATISTICS
154 is supported.
155 * ``PIPE_CAP_TEXTURE_BORDER_COLOR_QUIRK``: Bitmask indicating whether special
156 considerations have to be given to the interaction between the border color
157 in the sampler object and the sampler view used with it.
158 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_R600 is set, the border color
159 may be affected in undefined ways for any kind of permutational swizzle
160 (any swizzle XYZW where X/Y/Z/W are not ZERO, ONE, or R/G/B/A respectively)
161 in the sampler view.
162 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_NV50 is set, the border color
163 state should be swizzled manually according to the swizzle in the sampler
164 view it is intended to be used with, or herein undefined results may occur
165 for permutational swizzles.
166 * ``PIPE_CAP_MAX_TEXTURE_BUFFER_SIZE``: The maximum accessible size with
167 a buffer sampler view, in bytes.
168 * ``PIPE_CAP_MAX_VIEWPORTS``: The maximum number of viewports (and scissors
169 since they are linked) a driver can support. Returning 0 is equivalent
170 to returning 1 because every driver has to support at least a single
171 viewport/scissor combination.
172 * ``PIPE_CAP_ENDIANNESS``:: The endianness of the device. Either
173 PIPE_ENDIAN_BIG or PIPE_ENDIAN_LITTLE.
174 * ``PIPE_CAP_MIXED_FRAMEBUFFER_SIZES``: Whether it is allowed to have
175 different sizes for fb color/zs attachments. This controls whether
176 ARB_framebuffer_object is provided.
177 * ``PIPE_CAP_TGSI_VS_LAYER_VIEWPORT``: Whether ``TGSI_SEMANTIC_LAYER`` and
178 ``TGSI_SEMANTIC_VIEWPORT_INDEX`` are supported as vertex shader
179 outputs. Note that the viewport will only be used if multiple viewports are
180 exposed.
181 * ``PIPE_CAP_MAX_GEOMETRY_OUTPUT_VERTICES``: The maximum number of vertices
182 output by a single invocation of a geometry shader.
183 * ``PIPE_CAP_MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS``: The maximum number of
184 vertex components output by a single invocation of a geometry shader.
185 This is the product of the number of attribute components per vertex and
186 the number of output vertices.
187 * ``PIPE_CAP_MAX_TEXTURE_GATHER_COMPONENTS``: Max number of components
188 in format that texture gather can operate on. 1 == RED, ALPHA etc,
189 4 == All formats.
190 * ``PIPE_CAP_TEXTURE_GATHER_SM5``: Whether the texture gather
191 hardware implements the SM5 features, component selection,
192 shadow comparison, and run-time offsets.
193 * ``PIPE_CAP_BUFFER_MAP_PERSISTENT_COHERENT``: Whether
194 PIPE_TRANSFER_PERSISTENT and PIPE_TRANSFER_COHERENT are supported
195 for buffers.
196 * ``PIPE_CAP_TEXTURE_QUERY_LOD``: Whether the ``LODQ`` instruction is
197 supported.
198 * ``PIPE_CAP_MIN_TEXTURE_GATHER_OFFSET``: The minimum offset that can be used
199 in conjunction with a texture gather opcode.
200 * ``PIPE_CAP_MAX_TEXTURE_GATHER_OFFSET``: The maximum offset that can be used
201 in conjunction with a texture gather opcode.
202 * ``PIPE_CAP_SAMPLE_SHADING``: Whether there is support for per-sample
203 shading. The context->set_min_samples function will be expected to be
204 implemented.
205 * ``PIPE_CAP_TEXTURE_GATHER_OFFSETS``: Whether the ``TG4`` instruction can
206 accept 4 offsets.
207 * ``PIPE_CAP_TGSI_VS_WINDOW_SPACE_POSITION``: Whether
208 TGSI_PROPERTY_VS_WINDOW_SPACE_POSITION is supported, which disables clipping
209 and viewport transformation.
210 * ``PIPE_CAP_MAX_VERTEX_STREAMS``: The maximum number of vertex streams
211 supported by the geometry shader. If stream-out is supported, this should be
212 at least 1. If stream-out is not supported, this should be 0.
213 * ``PIPE_CAP_DRAW_INDIRECT``: Whether the driver supports taking draw arguments
214 { count, instance_count, start, index_bias } from a PIPE_BUFFER resource.
215 See pipe_draw_info.
216
217
218 .. _pipe_capf:
219
220 PIPE_CAPF_*
221 ^^^^^^^^^^^^^^^^
222
223 The floating-point capabilities are:
224
225 * ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line.
226 * ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
227 * ``PIPE_CAPF_MAX_POINT_WIDTH``: The maximum width and height of a point.
228 * ``PIPE_CAPF_MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
229 * ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
230 applied to anisotropically filtered textures.
231 * ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
232 to filtered textures.
233 * ``PIPE_CAPF_GUARD_BAND_LEFT``,
234 ``PIPE_CAPF_GUARD_BAND_TOP``,
235 ``PIPE_CAPF_GUARD_BAND_RIGHT``,
236 ``PIPE_CAPF_GUARD_BAND_BOTTOM``: TODO
237
238
239 .. _pipe_shader_cap:
240
241 PIPE_SHADER_CAP_*
242 ^^^^^^^^^^^^^^^^^
243
244 These are per-shader-stage capabitity queries. Different shader stages may
245 support different features.
246
247 * ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions.
248 * ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
249 * ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
250 * ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections.
251 * ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
252 * ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers.
253 * ``PIPE_SHADER_CAP_MAX_CONSTS``: The maximum number of constants.
254 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
255 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
256 only permit binding one constant buffer per shader, and the shaders will
257 not permit two-dimensional access to constants.
258
259 If a value greater than 0 is returned, the driver can have multiple
260 constant buffers bound to shader stages. The CONST register file can
261 be accessed with two-dimensional indices, like in the example below.
262
263 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0
264 DCL CONST[3][0] # declare first vector of constbuf 3
265 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0
266
267 For backwards compatibility, one-dimensional access to CONST register
268 file is still supported. In that case, the constbuf index is assumed
269 to be 0.
270
271 * ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers.
272 * ``PIPE_SHADER_CAP_MAX_ADDRS``: The maximum number of address registers.
273 * ``PIPE_SHADER_CAP_MAX_PREDS``: The maximum number of predicate registers.
274 * ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported.
275 * ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing
276 of the input file is supported.
277 * ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing
278 of the output file is supported.
279 * ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing
280 of the temporary file is supported.
281 * ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing
282 of the constant file is supported.
283 * ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e.
284 BGNSUB, ENDSUB, CAL, and RET, including RET in the main block.
285 * ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported.
286 If unsupported, only float opcodes are supported.
287 * ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: The maximum number of texture
288 samplers.
289 * ``PIPE_SHADER_CAP_PREFERRED_IR``: Preferred representation of the
290 program. It should be one of the ``pipe_shader_ir`` enum values.
291 * ``PIPE_SHADER_CAP_MAX_SAMPLER_VIEWS``: The maximum number of texture
292 sampler views. Must not be lower than PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS.
293 * ``PIPE_SHADER_CAP_DOUBLES``: Whether double precision floating-point
294 operations are supported.
295
296
297 .. _pipe_compute_cap:
298
299 PIPE_COMPUTE_CAP_*
300 ^^^^^^^^^^^^^^^^^^
301
302 Compute-specific capabilities. They can be queried using
303 pipe_screen::get_compute_param.
304
305 * ``PIPE_COMPUTE_CAP_IR_TARGET``: A description of the target of the form
306 ``processor-arch-manufacturer-os`` that will be passed on to the compiler.
307 This CAP is only relevant for drivers that specify PIPE_SHADER_IR_LLVM for
308 their preferred IR.
309 Value type: null-terminated string.
310 * ``PIPE_COMPUTE_CAP_GRID_DIMENSION``: Number of supported dimensions
311 for grid and block coordinates. Value type: ``uint64_t``.
312 * ``PIPE_COMPUTE_CAP_MAX_GRID_SIZE``: Maximum grid size in block
313 units. Value type: ``uint64_t []``.
314 * ``PIPE_COMPUTE_CAP_MAX_BLOCK_SIZE``: Maximum block size in thread
315 units. Value type: ``uint64_t []``.
316 * ``PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK``: Maximum number of threads that
317 a single block can contain. Value type: ``uint64_t``.
318 This may be less than the product of the components of MAX_BLOCK_SIZE and is
319 usually limited by the number of threads that can be resident simultaneously
320 on a compute unit.
321 * ``PIPE_COMPUTE_CAP_MAX_GLOBAL_SIZE``: Maximum size of the GLOBAL
322 resource. Value type: ``uint64_t``.
323 * ``PIPE_COMPUTE_CAP_MAX_LOCAL_SIZE``: Maximum size of the LOCAL
324 resource. Value type: ``uint64_t``.
325 * ``PIPE_COMPUTE_CAP_MAX_PRIVATE_SIZE``: Maximum size of the PRIVATE
326 resource. Value type: ``uint64_t``.
327 * ``PIPE_COMPUTE_CAP_MAX_INPUT_SIZE``: Maximum size of the INPUT
328 resource. Value type: ``uint64_t``.
329 * ``PIPE_COMPUTE_CAP_MAX_MEM_ALLOC_SIZE``: Maximum size of a memory object
330 allocation in bytes. Value type: ``uint64_t``.
331 * ``PIPE_COMPUTE_CAP_MAX_CLOCK_FREQUENCY``: Maximum frequency of the GPU
332 clock in MHz. Value type: ``uint32_t``
333 * ``PIPE_COMPUTE_CAP_MAX_COMPUTE_UNITS``: Maximum number of compute units
334 Value type: ``uint32_t``
335
336 .. _pipe_bind:
337
338 PIPE_BIND_*
339 ^^^^^^^^^^^
340
341 These flags indicate how a resource will be used and are specified at resource
342 creation time. Resources may be used in different roles
343 during their lifecycle. Bind flags are cumulative and may be combined to create
344 a resource which can be used for multiple things.
345 Depending on the pipe driver's memory management and these bind flags,
346 resources might be created and handled quite differently.
347
348 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
349 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs
350 must have this flag set.
351 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
352 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
353 have this flag set.
354 * ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to
355 query whether a device supports blending for a given format.
356 If this flag is set, surface creation may fail if blending is not supported
357 for the specified format. If it is not set, a driver may choose to ignore
358 blending on surfaces with formats that would require emulation.
359 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
360 pipe_screen::flush_front_buffer must have this flag set.
361 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
362 or vertex shader.
363 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
364 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
365 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
366 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to.
367 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from.
368 * ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer.
369 * ``PIPE_BIND_CUSTOM``:
370 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
371 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
372 process.
373 * ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global
374 address space of a compute program.
375 * ``PIPE_BIND_SHADER_RESOURCE``: A buffer or texture that can be
376 bound to the graphics pipeline as a shader resource.
377 * ``PIPE_BIND_COMPUTE_RESOURCE``: A buffer or texture that can be
378 bound to the compute program as a shader resource.
379 * ``PIPE_BIND_COMMAND_ARGS_BUFFER``: A buffer that may be sourced by the
380 GPU command processor. It can contain, for example, the arguments to
381 indirect draw calls.
382
383 .. _pipe_usage:
384
385 PIPE_USAGE_*
386 ^^^^^^^^^^^^
387
388 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
389 Note that drivers must always support read and write CPU access at any time
390 no matter which hint they got.
391
392 * ``PIPE_USAGE_DEFAULT``: Optimized for fast GPU access.
393 * ``PIPE_USAGE_IMMUTABLE``: Optimized for fast GPU access and the resource is
394 not expected to be mapped or changed (even by the GPU) after the first upload.
395 * ``PIPE_USAGE_DYNAMIC``: Expect frequent write-only CPU access. What is
396 uploaded is expected to be used at least several times by the GPU.
397 * ``PIPE_USAGE_STREAM``: Expect frequent write-only CPU access. What is
398 uploaded is expected to be used only once by the GPU.
399 * ``PIPE_USAGE_STAGING``: Optimized for fast CPU access.
400
401
402 Methods
403 -------
404
405 XXX to-do
406
407 get_name
408 ^^^^^^^^
409
410 Returns an identifying name for the screen.
411
412 get_vendor
413 ^^^^^^^^^^
414
415 Returns the screen vendor.
416
417 .. _get_param:
418
419 get_param
420 ^^^^^^^^^
421
422 Get an integer/boolean screen parameter.
423
424 **param** is one of the :ref:`PIPE_CAP` names.
425
426 .. _get_paramf:
427
428 get_paramf
429 ^^^^^^^^^^
430
431 Get a floating-point screen parameter.
432
433 **param** is one of the :ref:`PIPE_CAP` names.
434
435 context_create
436 ^^^^^^^^^^^^^^
437
438 Create a pipe_context.
439
440 **priv** is private data of the caller, which may be put to various
441 unspecified uses, typically to do with implementing swapbuffers
442 and/or front-buffer rendering.
443
444 is_format_supported
445 ^^^^^^^^^^^^^^^^^^^
446
447 Determine if a resource in the given format can be used in a specific manner.
448
449 **format** the resource format
450
451 **target** one of the PIPE_TEXTURE_x flags
452
453 **sample_count** the number of samples. 0 and 1 mean no multisampling,
454 the maximum allowed legal value is 32.
455
456 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
457
458 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags.
459
460 Returns TRUE if all usages can be satisfied.
461
462
463 can_create_resource
464 ^^^^^^^^^^^^^^^^^^^
465
466 Check if a resource can actually be created (but don't actually allocate any
467 memory). This is used to implement OpenGL's proxy textures. Typically, a
468 driver will simply check if the total size of the given resource is less than
469 some limit.
470
471
472 .. _resource_create:
473
474 resource_create
475 ^^^^^^^^^^^^^^^
476
477 Create a new resource from a template.
478 The following fields of the pipe_resource must be specified in the template:
479
480 **target** one of the pipe_texture_target enums.
481 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
482 Modern APIs allow using buffers as shader resources.
483
484 **format** one of the pipe_format enums.
485
486 **width0** the width of the base mip level of the texture or size of the buffer.
487
488 **height0** the height of the base mip level of the texture
489 (1 for 1D or 1D array textures).
490
491 **depth0** the depth of the base mip level of the texture
492 (1 for everything else).
493
494 **array_size** the array size for 1D and 2D array textures.
495 For cube maps this must be 6, for other textures 1.
496
497 **last_level** the last mip map level present.
498
499 **nr_samples** the nr of msaa samples. 0 (or 1) specifies a resource
500 which isn't multisampled.
501
502 **usage** one of the PIPE_USAGE flags.
503
504 **bind** bitmask of the PIPE_BIND flags.
505
506 **flags** bitmask of PIPE_RESOURCE_FLAG flags.
507
508
509
510 resource_destroy
511 ^^^^^^^^^^^^^^^^
512
513 Destroy a resource. A resource is destroyed if it has no more references.
514
515
516
517 get_timestamp
518 ^^^^^^^^^^^^^
519
520 Query a timestamp in nanoseconds. The returned value should match
521 PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't
522 wait for rendering to complete (which cannot be achieved with queries).
523
524
525
526 get_driver_query_info
527 ^^^^^^^^^^^^^^^^^^^^^
528
529 Return a driver-specific query. If the **info** parameter is NULL,
530 the number of available queries is returned. Otherwise, the driver
531 query at the specified **index** is returned in **info**.
532 The function returns non-zero on success.
533 The driver-specific query is described with the pipe_driver_query_info
534 structure.