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_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 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_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 63 MRTs. 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 82 in the vertex shader. 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 86 supported. That is, is the pipe_rasterizer_state::clamp_fragment_color 87 flag supported by the driver? If not, the state tracker will insert 88 clamping code into the fragment shaders when needed. 89 90 * ``PIPE_CAP_MIXED_COLORBUFFER_FORMATS``: Whether mixed colorbuffer formats are 91 supported, e.g. RGBA8 and RGBA32F as the first and second colorbuffer, resp. 92 * ``PIPE_CAP_VERTEX_COLOR_UNCLAMPED``: Whether the driver is capable of 93 outputting unclamped vertex colors from a vertex shader. If unsupported, 94 the vertex colors are always clamped. This is the default for DX9 hardware. 95 * ``PIPE_CAP_VERTEX_COLOR_CLAMPED``: Whether the driver is capable of 96 clamping vertex colors when they come out of a vertex shader, as specified 97 by the pipe_rasterizer_state::clamp_vertex_color flag. If unsupported, 98 the vertex colors are never clamped. This is the default for DX10 hardware. 99 If both clamped and unclamped CAPs are supported, the clamping can be 100 controlled through pipe_rasterizer_state. If the driver cannot do vertex 101 color clamping, the state tracker may insert clamping code into the vertex 102 shader. 103 * ``PIPE_CAP_GLSL_FEATURE_LEVEL``: Whether the driver supports features 104 equivalent to a specific GLSL version. E.g. for GLSL 1.3, report 130. 105 * ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION``: Whether quads adhere to 106 the flatshade_first setting in ``pipe_rasterizer_state``. 107 * ``PIPE_CAP_USER_VERTEX_BUFFERS``: Whether the driver supports user vertex 108 buffers. If not, the state tracker must upload all data which is not in hw 109 resources. 110 * ``PIPE_CAP_VERTEX_BUFFER_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes a hw 111 limitation. If true, pipe_vertex_buffer::buffer_offset must always be aligned 112 to 4. If false, there are no restrictions on the offset. 113 * ``PIPE_CAP_VERTEX_BUFFER_STRIDE_4BYTE_ALIGNED_ONLY``: This CAP describes a hw 114 limitation. If true, pipe_vertex_buffer::stride must always be aligned to 4. 115 If false, there are no restrictions on the stride. 116 * ``PIPE_CAP_VERTEX_ELEMENT_SRC_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes 117 a hw limitation. If true, pipe_vertex_element::src_offset must always be 118 aligned to 4. If false, there are no restrictions on src_offset. 119 * ``PIPE_CAP_COMPUTE``: Whether the implementation supports the 120 compute entry points defined in pipe_context and pipe_screen. 121 * ``PIPE_CAP_USER_INDEX_BUFFERS``: Whether user index buffers are supported. 122 If not, the state tracker must upload all indices which are not in hw 123 resources. 124 * ``PIPE_CAP_USER_CONSTANT_BUFFERS``: Whether user constant buffers are 125 supported. If not, the state tracker must upload constants which are not in hw 126 resources. 127 * ``PIPE_CAP_CONSTANT_BUFFER_OFFSET_ALIGNMENT``: Describes the required 128 alignment of pipe_constant_buffer::buffer_offset. 129 * ``PIPE_CAP_START_INSTANCE``: Whether the driver supports 130 pipe_draw_info::start_instance. 131 * ``PIPE_CAP_QUERY_TIMESTAMP``: Whether PIPE_QUERY_TIMESTAMP and 132 the pipe_screen::get_timestamp hook are implemented. 133 134 135 .. _pipe_capf: 136 137 PIPE_CAPF_* 138 ^^^^^^^^^^^^^^^^ 139 140 The floating-point capabilities are: 141 142 * ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line. 143 * ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line. 144 * ``PIPE_CAPF_MAX_POINT_WIDTH``: The maximum width and height of a point. 145 * ``PIPE_CAPF_MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point. 146 * ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be 147 applied to anisotropically filtered textures. 148 * ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied 149 to filtered textures. 150 * ``PIPE_CAPF_GUARD_BAND_LEFT``, 151 ``PIPE_CAPF_GUARD_BAND_TOP``, 152 ``PIPE_CAPF_GUARD_BAND_RIGHT``, 153 ``PIPE_CAPF_GUARD_BAND_BOTTOM``: TODO 154 155 156 .. _pipe_shader_cap: 157 158 PIPE_SHADER_CAP_* 159 ^^^^^^^^^^^^^^^^^ 160 161 These are per-shader-stage capabitity queries. Different shader stages may 162 support different features. 163 164 * ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions. 165 * ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions. 166 * ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions. 167 * ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections. 168 * ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth. 169 * ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers. 170 * ``PIPE_SHADER_CAP_MAX_CONSTS``: The maximum number of constants. 171 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound 172 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will 173 only permit binding one constant buffer per shader, and the shaders will 174 not permit two-dimensional access to constants. 175 176 If a value greater than 0 is returned, the driver can have multiple 177 constant buffers bound to shader stages. The CONST register file can 178 be accessed with two-dimensional indices, like in the example below. 179 180 DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0 181 DCL CONST[3][0] # declare first vector of constbuf 3 182 MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0 183 184 For backwards compatibility, one-dimensional access to CONST register 185 file is still supported. In that case, the constbuf index is assumed 186 to be 0. 187 188 * ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers. 189 * ``PIPE_SHADER_CAP_MAX_ADDRS``: The maximum number of address registers. 190 * ``PIPE_SHADER_CAP_MAX_PREDS``: The maximum number of predicate registers. 191 * ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported. 192 * ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing 193 of the input file is supported. 194 * ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing 195 of the output file is supported. 196 * ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing 197 of the temporary file is supported. 198 * ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing 199 of the constant file is supported. 200 * ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e. 201 BGNSUB, ENDSUB, CAL, and RET, including RET in the main block. 202 * ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported. 203 If unsupported, only float opcodes are supported. 204 * ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: THe maximum number of texture 205 samplers. 206 * ``PIPE_SHADER_CAP_PREFERRED_IR``: Preferred representation of the 207 program. It should be one of the ``pipe_shader_ir`` enum values. 208 209 210 .. _pipe_compute_cap: 211 212 PIPE_COMPUTE_CAP_* 213 ^^^^^^^^^^^^^^^^^^ 214 215 Compute-specific capabilities. They can be queried using 216 pipe_screen::get_compute_param. 217 218 * ``PIPE_COMPUTE_CAP_IR_TARGET``: A description of the target as a target 219 triple specification of the form ``processor-manufacturer-os`` that will 220 be passed on to the compiler. This CAP is only relevant for drivers 221 that specify PIPE_SHADER_IR_LLVM for their preferred IR. 222 Value type: null-terminated string. 223 * ``PIPE_COMPUTE_CAP_GRID_DIMENSION``: Number of supported dimensions 224 for grid and block coordinates. Value type: ``uint64_t``. 225 * ``PIPE_COMPUTE_CAP_MAX_GRID_SIZE``: Maximum grid size in block 226 units. Value type: ``uint64_t []``. 227 * ``PIPE_COMPUTE_CAP_MAX_BLOCK_SIZE``: Maximum block size in thread 228 units. Value type: ``uint64_t []``. 229 * ``PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK``: Maximum number of threads that 230 a single block can contain. Value type: ``uint64_t``. 231 This may be less than the product of the components of MAX_BLOCK_SIZE and is 232 usually limited by the number of threads that can be resident simultaneously 233 on a compute unit. 234 * ``PIPE_COMPUTE_CAP_MAX_GLOBAL_SIZE``: Maximum size of the GLOBAL 235 resource. Value type: ``uint64_t``. 236 * ``PIPE_COMPUTE_CAP_MAX_LOCAL_SIZE``: Maximum size of the LOCAL 237 resource. Value type: ``uint64_t``. 238 * ``PIPE_COMPUTE_CAP_MAX_PRIVATE_SIZE``: Maximum size of the PRIVATE 239 resource. Value type: ``uint64_t``. 240 * ``PIPE_COMPUTE_CAP_MAX_INPUT_SIZE``: Maximum size of the INPUT 241 resource. Value type: ``uint64_t``. 242 243 .. _pipe_bind: 244 245 PIPE_BIND_* 246 ^^^^^^^^^^^ 247 248 These flags indicate how a resource will be used and are specified at resource 249 creation time. Resources may be used in different roles 250 during their lifecycle. Bind flags are cumulative and may be combined to create 251 a resource which can be used for multiple things. 252 Depending on the pipe driver's memory management and these bind flags, 253 resources might be created and handled quite differently. 254 255 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be 256 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs 257 must have this flag set. 258 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any 259 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must 260 have this flag set. 261 * ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to 262 query whether a device supports blending for a given format. 263 If this flag is set, surface creation may fail if blending is not supported 264 for the specified format. If it is not set, a driver may choose to ignore 265 blending on surfaces with formats that would require emulation. 266 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to 267 pipe_screen::flush_front_buffer must have this flag set. 268 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment 269 or vertex shader. 270 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer. 271 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer. 272 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants. 273 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to. 274 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from. 275 * ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer. 276 * ``PIPE_BIND_CUSTOM``: 277 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer. 278 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another 279 process. 280 * ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global 281 address space of a compute program. 282 * ``PIPE_BIND_SHADER_RESOURCE``: A buffer or texture that can be 283 bound to the graphics pipeline as a shader resource. 284 * ``PIPE_BIND_COMPUTE_RESOURCE``: A buffer or texture that can be 285 bound to the compute program as a shader resource. 286 287 .. _pipe_usage: 288 289 PIPE_USAGE_* 290 ^^^^^^^^^^^^ 291 292 The PIPE_USAGE enums are hints about the expected usage pattern of a resource. 293 294 * ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws. 295 * ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws. 296 * ``PIPE_USAGE_STATIC``: Same as immutable (?) 297 * ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload. 298 * ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ... 299 300 301 Methods 302 ------- 303 304 XXX to-do 305 306 get_name 307 ^^^^^^^^ 308 309 Returns an identifying name for the screen. 310 311 get_vendor 312 ^^^^^^^^^^ 313 314 Returns the screen vendor. 315 316 .. _get_param: 317 318 get_param 319 ^^^^^^^^^ 320 321 Get an integer/boolean screen parameter. 322 323 **param** is one of the :ref:`PIPE_CAP` names. 324 325 .. _get_paramf: 326 327 get_paramf 328 ^^^^^^^^^^ 329 330 Get a floating-point screen parameter. 331 332 **param** is one of the :ref:`PIPE_CAP` names. 333 334 context_create 335 ^^^^^^^^^^^^^^ 336 337 Create a pipe_context. 338 339 **priv** is private data of the caller, which may be put to various 340 unspecified uses, typically to do with implementing swapbuffers 341 and/or front-buffer rendering. 342 343 is_format_supported 344 ^^^^^^^^^^^^^^^^^^^ 345 346 Determine if a resource in the given format can be used in a specific manner. 347 348 **format** the resource format 349 350 **target** one of the PIPE_TEXTURE_x flags 351 352 **sample_count** the number of samples. 0 and 1 mean no multisampling, 353 the maximum allowed legal value is 32. 354 355 **bindings** is a bitmask of :ref:`PIPE_BIND` flags. 356 357 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags. 358 359 Returns TRUE if all usages can be satisfied. 360 361 .. _resource_create: 362 363 resource_create 364 ^^^^^^^^^^^^^^^ 365 366 Create a new resource from a template. 367 The following fields of the pipe_resource must be specified in the template: 368 369 **target** one of the pipe_texture_target enums. 370 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different. 371 Modern APIs allow using buffers as shader resources. 372 373 **format** one of the pipe_format enums. 374 375 **width0** the width of the base mip level of the texture or size of the buffer. 376 377 **height0** the height of the base mip level of the texture 378 (1 for 1D or 1D array textures). 379 380 **depth0** the depth of the base mip level of the texture 381 (1 for everything else). 382 383 **array_size** the array size for 1D and 2D array textures. 384 For cube maps this must be 6, for other textures 1. 385 386 **last_level** the last mip map level present. 387 388 **nr_samples** the nr of msaa samples. 0 (or 1) specifies a resource 389 which isn't multisampled. 390 391 **usage** one of the PIPE_USAGE flags. 392 393 **bind** bitmask of the PIPE_BIND flags. 394 395 **flags** bitmask of PIPE_RESOURCE_FLAG flags. 396 397 398 399 resource_destroy 400 ^^^^^^^^^^^^^^^^ 401 402 Destroy a resource. A resource is destroyed if it has no more references. 403 404 405 406 get_timestamp 407 ^^^^^^^^^^^^^ 408 409 Query a timestamp in nanoseconds. The returned value should match 410 PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't 411 wait for rendering to complete (which cannot be achieved with queries). 412
