1.. _screen: 2 3Screen 4====== 5 6A screen is an object representing the context-independent part of a device. 7 8Flags and enumerations 9---------------------- 10 11XXX some of these don't belong in this section. 12 13 14.. _pipe_cap: 15 16PIPE_CAP_* 17^^^^^^^^^^ 18 19Capability queries return information about the features and limits of the 20driver/GPU. For floating-point values, use :ref:`get_paramf`, and for boolean 21or integer values, use :ref:`get_param`. 22 23The 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.offset, in bytes. 140 If a driver does not support offset/size, it should return 0. 141* ``PIPE_CAP_BUFFER_SAMPLER_VIEW_RGBA_ONLY``: Whether the driver only 142 supports R, RG, RGB and RGBA formats for PIPE_BUFFER sampler views. 143 When this is the case it should be assumed that the swizzle parameters 144 in the sampler view have no effect. 145* ``PIPE_CAP_TGSI_TEXCOORD``: This CAP describes a hw limitation. 146 If true, the hardware cannot replace arbitrary shader inputs with sprite 147 coordinates and hence the inputs that are desired to be replaceable must 148 be declared with TGSI_SEMANTIC_TEXCOORD instead of TGSI_SEMANTIC_GENERIC. 149 The rasterizer's sprite_coord_enable state therefore also applies to the 150 TEXCOORD semantic. 151 Also, TGSI_SEMANTIC_PCOORD becomes available, which labels a fragment shader 152 input that will always be replaced with sprite coordinates. 153* ``PIPE_CAP_PREFER_BLIT_BASED_TEXTURE_TRANSFER``: Whether it is preferable 154 to use a blit to implement a texture transfer which needs format conversions 155 and swizzling in state trackers. Generally, all hardware drivers with 156 dedicated memory should return 1 and all software rasterizers should return 0. 157* ``PIPE_CAP_QUERY_PIPELINE_STATISTICS``: Whether PIPE_QUERY_PIPELINE_STATISTICS 158 is supported. 159* ``PIPE_CAP_TEXTURE_BORDER_COLOR_QUIRK``: Bitmask indicating whether special 160 considerations have to be given to the interaction between the border color 161 in the sampler object and the sampler view used with it. 162 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_R600 is set, the border color 163 may be affected in undefined ways for any kind of permutational swizzle 164 (any swizzle XYZW where X/Y/Z/W are not ZERO, ONE, or R/G/B/A respectively) 165 in the sampler view. 166 If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_NV50 is set, the border color 167 state should be swizzled manually according to the swizzle in the sampler 168 view it is intended to be used with, or herein undefined results may occur 169 for permutational swizzles. 170* ``PIPE_CAP_MAX_TEXTURE_BUFFER_SIZE``: The maximum accessible size with 171 a buffer sampler view, in texels. 172* ``PIPE_CAP_MAX_VIEWPORTS``: The maximum number of viewports (and scissors 173 since they are linked) a driver can support. Returning 0 is equivalent 174 to returning 1 because every driver has to support at least a single 175 viewport/scissor combination. 176* ``PIPE_CAP_ENDIANNESS``:: The endianness of the device. Either 177 PIPE_ENDIAN_BIG or PIPE_ENDIAN_LITTLE. 178* ``PIPE_CAP_MIXED_FRAMEBUFFER_SIZES``: Whether it is allowed to have 179 different sizes for fb color/zs attachments. This controls whether 180 ARB_framebuffer_object is provided. 181* ``PIPE_CAP_TGSI_VS_LAYER_VIEWPORT``: Whether ``TGSI_SEMANTIC_LAYER`` and 182 ``TGSI_SEMANTIC_VIEWPORT_INDEX`` are supported as vertex shader 183 outputs. Note that the viewport will only be used if multiple viewports are 184 exposed. 185* ``PIPE_CAP_MAX_GEOMETRY_OUTPUT_VERTICES``: The maximum number of vertices 186 output by a single invocation of a geometry shader. 187* ``PIPE_CAP_MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS``: The maximum number of 188 vertex components output by a single invocation of a geometry shader. 189 This is the product of the number of attribute components per vertex and 190 the number of output vertices. 191* ``PIPE_CAP_MAX_TEXTURE_GATHER_COMPONENTS``: Max number of components 192 in format that texture gather can operate on. 1 == RED, ALPHA etc, 193 4 == All formats. 194* ``PIPE_CAP_TEXTURE_GATHER_SM5``: Whether the texture gather 195 hardware implements the SM5 features, component selection, 196 shadow comparison, and run-time offsets. 197* ``PIPE_CAP_BUFFER_MAP_PERSISTENT_COHERENT``: Whether 198 PIPE_TRANSFER_PERSISTENT and PIPE_TRANSFER_COHERENT are supported 199 for buffers. 200* ``PIPE_CAP_TEXTURE_QUERY_LOD``: Whether the ``LODQ`` instruction is 201 supported. 202* ``PIPE_CAP_MIN_TEXTURE_GATHER_OFFSET``: The minimum offset that can be used 203 in conjunction with a texture gather opcode. 204* ``PIPE_CAP_MAX_TEXTURE_GATHER_OFFSET``: The maximum offset that can be used 205 in conjunction with a texture gather opcode. 206* ``PIPE_CAP_SAMPLE_SHADING``: Whether there is support for per-sample 207 shading. The context->set_min_samples function will be expected to be 208 implemented. 209* ``PIPE_CAP_TEXTURE_GATHER_OFFSETS``: Whether the ``TG4`` instruction can 210 accept 4 offsets. 211* ``PIPE_CAP_TGSI_VS_WINDOW_SPACE_POSITION``: Whether 212 TGSI_PROPERTY_VS_WINDOW_SPACE_POSITION is supported, which disables clipping 213 and viewport transformation. 214* ``PIPE_CAP_MAX_VERTEX_STREAMS``: The maximum number of vertex streams 215 supported by the geometry shader. If stream-out is supported, this should be 216 at least 1. If stream-out is not supported, this should be 0. 217* ``PIPE_CAP_DRAW_INDIRECT``: Whether the driver supports taking draw arguments 218 { count, instance_count, start, index_bias } from a PIPE_BUFFER resource. 219 See pipe_draw_info. 220* ``PIPE_CAP_MULTI_DRAW_INDIRECT``: Whether the driver supports 221 pipe_draw_info::indirect_stride and ::indirect_count 222* ``PIPE_CAP_MULTI_DRAW_INDIRECT_PARAMS``: Whether the driver supports 223 taking the number of indirect draws from a separate parameter 224 buffer, see pipe_draw_info::indirect_params. 225* ``PIPE_CAP_TGSI_FS_FINE_DERIVATIVE``: Whether the fragment shader supports 226 the FINE versions of DDX/DDY. 227* ``PIPE_CAP_VENDOR_ID``: The vendor ID of the underlying hardware. If it's 228 not available one should return 0xFFFFFFFF. 229* ``PIPE_CAP_DEVICE_ID``: The device ID (PCI ID) of the underlying hardware. 230 0xFFFFFFFF if not available. 231* ``PIPE_CAP_ACCELERATED``: Whether the renderer is hardware accelerated. 232* ``PIPE_CAP_VIDEO_MEMORY``: The amount of video memory in megabytes. 233* ``PIPE_CAP_UMA``: If the device has a unified memory architecture or on-card 234 memory and GART. 235* ``PIPE_CAP_CONDITIONAL_RENDER_INVERTED``: Whether the driver supports inverted 236 condition for conditional rendering. 237* ``PIPE_CAP_MAX_VERTEX_ATTRIB_STRIDE``: The maximum supported vertex stride. 238* ``PIPE_CAP_SAMPLER_VIEW_TARGET``: Whether the sampler view's target can be 239 different than the underlying resource's, as permitted by 240 ARB_texture_view. For example a 2d array texture may be reinterpreted as a 241 cube (array) texture and vice-versa. 242* ``PIPE_CAP_CLIP_HALFZ``: Whether the driver supports the 243 pipe_rasterizer_state::clip_halfz being set to true. This is required 244 for enabling ARB_clip_control. 245* ``PIPE_CAP_VERTEXID_NOBASE``: If true, the driver only supports 246 TGSI_SEMANTIC_VERTEXID_NOBASE (and not TGSI_SEMANTIC_VERTEXID). This means 247 state trackers for APIs whose vertexIDs are offset by basevertex (such as GL) 248 will need to lower TGSI_SEMANTIC_VERTEXID to TGSI_SEMANTIC_VERTEXID_NOBASE 249 and TGSI_SEMANTIC_BASEVERTEX, so drivers setting this must handle both these 250 semantics. Only relevant if geometry shaders are supported. 251 (BASEVERTEX could be exposed separately too via ``PIPE_CAP_DRAW_PARAMETERS``). 252* ``PIPE_CAP_POLYGON_OFFSET_CLAMP``: If true, the driver implements support 253 for ``pipe_rasterizer_state::offset_clamp``. 254* ``PIPE_CAP_MULTISAMPLE_Z_RESOLVE``: Whether the driver supports blitting 255 a multisampled depth buffer into a single-sampled texture (or depth buffer). 256 Only the first sampled should be copied. 257* ``PIPE_CAP_RESOURCE_FROM_USER_MEMORY``: Whether the driver can create 258 a pipe_resource where an already-existing piece of (malloc'd) user memory 259 is used as its backing storage. In other words, whether the driver can map 260 existing user memory into the device address space for direct device access. 261 The create function is pipe_screen::resource_from_user_memory. The address 262 and size must be page-aligned. 263* ``PIPE_CAP_DEVICE_RESET_STATUS_QUERY``: 264 Whether pipe_context::get_device_reset_status is implemented. 265* ``PIPE_CAP_MAX_SHADER_PATCH_VARYINGS``: 266 How many per-patch outputs and inputs are supported between tessellation 267 control and tessellation evaluation shaders, not counting in TESSINNER and 268 TESSOUTER. The minimum allowed value for OpenGL is 30. 269* ``PIPE_CAP_TEXTURE_FLOAT_LINEAR``: Whether the linear minification and 270 magnification filters are supported with single-precision floating-point 271 textures. 272* ``PIPE_CAP_TEXTURE_HALF_FLOAT_LINEAR``: Whether the linear minification and 273 magnification filters are supported with half-precision floating-point 274 textures. 275* ``PIPE_CAP_DEPTH_BOUNDS_TEST``: Whether bounds_test, bounds_min, and 276 bounds_max states of pipe_depth_stencil_alpha_state behave according 277 to the GL_EXT_depth_bounds_test specification. 278* ``PIPE_CAP_TGSI_TXQS``: Whether the `TXQS` opcode is supported 279* ``PIPE_CAP_FORCE_PERSAMPLE_INTERP``: If the driver can force per-sample 280 interpolation for all fragment shader inputs if 281 pipe_rasterizer_state::force_persample_interp is set. This is only used 282 by GL3-level sample shading (ARB_sample_shading). GL4-level sample shading 283 (ARB_gpu_shader5) doesn't use this. While GL3 hardware has a state for it, 284 GL4 hardware will likely need to emulate it with a shader variant, or by 285 selecting the interpolation weights with a conditional assignment 286 in the shader. 287* ``PIPE_CAP_SHAREABLE_SHADERS``: Whether shader CSOs can be used by any 288 pipe_context. 289* ``PIPE_CAP_COPY_BETWEEN_COMPRESSED_AND_PLAIN_FORMATS``: 290 Whether copying between compressed and plain formats is supported where 291 a compressed block is copied to/from a plain pixel of the same size. 292* ``PIPE_CAP_CLEAR_TEXTURE``: Whether `clear_texture` will be 293 available in contexts. 294* ``PIPE_CAP_DRAW_PARAMETERS``: Whether ``TGSI_SEMANTIC_BASEVERTEX``, 295 ``TGSI_SEMANTIC_BASEINSTANCE``, and ``TGSI_SEMANTIC_DRAWID`` are 296 supported in vertex shaders. 297* ``PIPE_CAP_TGSI_PACK_HALF_FLOAT``: Whether the ``UP2H`` and ``PK2H`` 298 TGSI opcodes are supported. 299* ``PIPE_CAP_TGSI_FS_POSITION_IS_SYSVAL``: If state trackers should use 300 a system value for the POSITION fragment shader input. 301* ``PIPE_CAP_TGSI_FS_FACE_IS_INTEGER_SYSVAL``: If state trackers should use 302 a system value for the FACE fragment shader input. 303 Also, the FACE system value is integer, not float. 304* ``PIPE_CAP_SHADER_BUFFER_OFFSET_ALIGNMENT``: Describes the required 305 alignment for pipe_shader_buffer::buffer_offset, in bytes. Maximum 306 value allowed is 256 (for GL conformance). 0 is only allowed if 307 shader buffers are not supported. 308* ``PIPE_CAP_INVALIDATE_BUFFER``: Whether the use of ``invalidate_resource`` 309 for buffers is supported. 310* ``PIPE_CAP_GENERATE_MIPMAP``: Indicates whether pipe_context::generate_mipmap 311 is supported. 312* ``PIPE_CAP_STRING_MARKER``: Whether pipe->emit_string_marker() is supported. 313* ``PIPE_CAP_SURFACE_REINTERPRET_BLOCKS``: Indicates whether 314 pipe_context::create_surface supports reinterpreting a texture as a surface 315 of a format with different block width/height (but same block size in bits). 316 For example, a compressed texture image can be interpreted as a 317 non-compressed surface whose texels are the same number of bits as the 318 compressed blocks, and vice versa. The width and height of the surface is 319 adjusted appropriately. 320* ``PIPE_CAP_QUERY_BUFFER_OBJECT``: Driver supports 321 context::get_query_result_resource callback. 322* ``PIPE_CAP_PCI_GROUP``: Return the PCI segment group number. 323* ``PIPE_CAP_PCI_BUS``: Return the PCI bus number. 324* ``PIPE_CAP_PCI_DEVICE``: Return the PCI device number. 325* ``PIPE_CAP_PCI_FUNCTION``: Return the PCI function number. 326* ``PIPE_CAP_FRAMEBUFFER_NO_ATTACHMENT``: 327 If non-zero, rendering to framebuffers with no surface attachments 328 is supported. The context->is_format_supported function will be expected 329 to be implemented with PIPE_FORMAT_NONE yeilding the MSAA modes the hardware 330 supports. N.B., The maximum number of layers supported for rasterizing a 331 primitive on a layer is obtained from ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS`` 332 even though it can be larger than the number of layers supported by either 333 rendering or textures. 334* ``PIPE_CAP_ROBUST_BUFFER_ACCESS_BEHAVIOR``: Implementation uses bounds 335 checking on resource accesses by shader if the context is created with 336 PIPE_CONTEXT_ROBUST_BUFFER_ACCESS. See the ARB_robust_buffer_access_behavior 337 extension for information on the required behavior for out of bounds accesses 338 and accesses to unbound resources. 339* ``PIPE_CAP_CULL_DISTANCE``: Whether the driver supports the arb_cull_distance 340 extension and thus implements proper support for culling planes. 341* ``PIPE_CAP_PRIMITIVE_RESTART_FOR_PATCHES``: Whether primitive restart is 342 supported for patch primitives. 343* ``PIPE_CAP_TGSI_VOTE``: Whether the ``VOTE_*`` ops can be used in shaders. 344* ``PIPE_CAP_MAX_WINDOW_RECTANGLES``: The maxium number of window rectangles 345 supported in ``set_window_rectangles``. 346* ``PIPE_CAP_POLYGON_OFFSET_UNITS_UNSCALED``: If true, the driver implements support 347 for ``pipe_rasterizer_state::offset_units_unscaled``. 348* ``PIPE_CAP_VIEWPORT_SUBPIXEL_BITS``: Number of bits of subpixel precision for 349 floating point viewport bounds. 350* ``PIPE_CAP_MIXED_COLOR_DEPTH_BITS``: Whether there is non-fallback 351 support for color/depth format combinations that use a different 352 number of bits. For the purpose of this cap, Z24 is treated as 353 32-bit. If set to off, that means that a B5G6R5 + Z24 or RGBA8 + Z16 354 combination will require a driver fallback, and should not be 355 advertised in the GLX/EGL config list. 356* ``PIPE_CAP_TGSI_ARRAY_COMPONENTS``: If true, the driver interprets the 357 UsageMask of input and output declarations and allows declaring arrays 358 in overlapping ranges. The components must be a contiguous range, e.g. a 359 UsageMask of xy or yzw is allowed, but xz or yw isn't. Declarations with 360 overlapping locations must have matching semantic names and indices, and 361 equal interpolation qualifiers. 362 Components may overlap, notably when the gaps in an array of dvec3 are 363 filled in. 364* ``PIPE_CAP_STREAM_OUTPUT_INTERLEAVE_BUFFERS``: Whether interleaved stream 365 output mode is able to interleave across buffers. This is required for 366 ARB_transform_feedback3. 367* ``PIPE_CAP_TGSI_CAN_READ_OUTPUTS``: Whether every TGSI shader stage can read 368 from the output file. 369* ``PIPE_CAP_GLSL_OPTIMIZE_CONSERVATIVELY``: Tell the GLSL compiler to use 370 the minimum amount of optimizations just to be able to do all the linking 371 and lowering. 372* ``PIPE_CAP_TGSI_FS_FBFETCH``: Whether a fragment shader can use the FBFETCH 373 opcode to retrieve the current value in the framebuffer. 374 375 376.. _pipe_capf: 377 378PIPE_CAPF_* 379^^^^^^^^^^^^^^^^ 380 381The floating-point capabilities are: 382 383* ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line. 384* ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line. 385* ``PIPE_CAPF_MAX_POINT_WIDTH``: The maximum width and height of a point. 386* ``PIPE_CAPF_MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point. 387* ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be 388 applied to anisotropically filtered textures. 389* ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied 390 to filtered textures. 391* ``PIPE_CAPF_GUARD_BAND_LEFT``, 392 ``PIPE_CAPF_GUARD_BAND_TOP``, 393 ``PIPE_CAPF_GUARD_BAND_RIGHT``, 394 ``PIPE_CAPF_GUARD_BAND_BOTTOM``: TODO 395 396 397.. _pipe_shader_cap: 398 399PIPE_SHADER_CAP_* 400^^^^^^^^^^^^^^^^^ 401 402These are per-shader-stage capabitity queries. Different shader stages may 403support different features. 404 405* ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions. 406* ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions. 407* ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions. 408* ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections. 409* ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth. 410* ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers. 411* ``PIPE_SHADER_CAP_MAX_OUTPUTS``: The maximum number of output registers. 412 This is valid for all shaders except the fragment shader. 413* ``PIPE_SHADER_CAP_MAX_CONST_BUFFER_SIZE``: The maximum size per constant buffer in bytes. 414* ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound 415 to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will 416 only permit binding one constant buffer per shader, and the shaders will 417 not permit two-dimensional access to constants. 418 419If a value greater than 0 is returned, the driver can have multiple 420constant buffers bound to shader stages. The CONST register file can 421be accessed with two-dimensional indices, like in the example below. 422 423DCL CONST[0][0..7] # declare first 8 vectors of constbuf 0 424DCL CONST[3][0] # declare first vector of constbuf 3 425MOV OUT[0], CONST[0][3] # copy vector 3 of constbuf 0 426 427For backwards compatibility, one-dimensional access to CONST register 428file is still supported. In that case, the constbuf index is assumed 429to be 0. 430 431* ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers. 432* ``PIPE_SHADER_CAP_MAX_PREDS``: The maximum number of predicate registers. 433* ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported. 434* ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing 435 of the input file is supported. 436* ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing 437 of the output file is supported. 438* ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing 439 of the temporary file is supported. 440* ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing 441 of the constant file is supported. 442* ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e. 443 BGNSUB, ENDSUB, CAL, and RET, including RET in the main block. 444* ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported. 445 If unsupported, only float opcodes are supported. 446* ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: The maximum number of texture 447 samplers. 448* ``PIPE_SHADER_CAP_PREFERRED_IR``: Preferred representation of the 449 program. It should be one of the ``pipe_shader_ir`` enum values. 450* ``PIPE_SHADER_CAP_MAX_SAMPLER_VIEWS``: The maximum number of texture 451 sampler views. Must not be lower than PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS. 452* ``PIPE_SHADER_CAP_DOUBLES``: Whether double precision floating-point 453 operations are supported. 454* ``PIPE_SHADER_CAP_TGSI_DROUND_SUPPORTED``: Whether double precision rounding 455 is supported. If it is, DTRUNC/DCEIL/DFLR/DROUND opcodes may be used. 456* ``PIPE_SHADER_CAP_TGSI_DFRACEXP_DLDEXP_SUPPORTED``: Whether DFRACEXP and 457 DLDEXP are supported. 458* ``PIPE_SHADER_CAP_TGSI_FMA_SUPPORTED``: Whether FMA and DFMA (doubles only) 459 are supported. 460* ``PIPE_SHADER_CAP_TGSI_ANY_INOUT_DECL_RANGE``: Whether the driver doesn't 461 ignore tgsi_declaration_range::Last for shader inputs and outputs. 462* ``PIPE_SHADER_CAP_MAX_UNROLL_ITERATIONS_HINT``: This is the maximum number 463 of iterations that loops are allowed to have to be unrolled. It is only 464 a hint to state trackers. Whether any loops will be unrolled is not 465 guaranteed. 466* ``PIPE_SHADER_CAP_MAX_SHADER_BUFFERS``: Maximum number of memory buffers 467 (also used to implement atomic counters). Having this be non-0 also 468 implies support for the ``LOAD``, ``STORE``, and ``ATOM*`` TGSI 469 opcodes. 470* ``PIPE_SHADER_CAP_SUPPORTED_IRS``: Supported representations of the 471 program. It should be a mask of ``pipe_shader_ir`` bits. 472* ``PIPE_SHADER_CAP_MAX_SHADER_IMAGES``: Maximum number of image units. 473* ``PIPE_SHADER_CAP_LOWER_IF_THRESHOLD``: IF and ELSE branches with a lower 474 cost than this value should be lowered by the state tracker for better 475 performance. This is a tunable for the GLSL compiler and the behavior is 476 specific to the compiler. 477 478 479.. _pipe_compute_cap: 480 481PIPE_COMPUTE_CAP_* 482^^^^^^^^^^^^^^^^^^ 483 484Compute-specific capabilities. They can be queried using 485pipe_screen::get_compute_param. 486 487* ``PIPE_COMPUTE_CAP_IR_TARGET``: A description of the target of the form 488 ``processor-arch-manufacturer-os`` that will be passed on to the compiler. 489 This CAP is only relevant for drivers that specify PIPE_SHADER_IR_LLVM 490 or PIPE_SHADER_IR_NATIVE for their preferred IR. 491 Value type: null-terminated string. Shader IR type dependent. 492* ``PIPE_COMPUTE_CAP_GRID_DIMENSION``: Number of supported dimensions 493 for grid and block coordinates. Value type: ``uint64_t``. Shader IR type dependent. 494* ``PIPE_COMPUTE_CAP_MAX_GRID_SIZE``: Maximum grid size in block 495 units. Value type: ``uint64_t []``. Shader IR type dependent. 496* ``PIPE_COMPUTE_CAP_MAX_BLOCK_SIZE``: Maximum block size in thread 497 units. Value type: ``uint64_t []``. Shader IR type dependent. 498* ``PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK``: Maximum number of threads that 499 a single block can contain. Value type: ``uint64_t``. Shader IR type dependent. 500 This may be less than the product of the components of MAX_BLOCK_SIZE and is 501 usually limited by the number of threads that can be resident simultaneously 502 on a compute unit. 503* ``PIPE_COMPUTE_CAP_MAX_GLOBAL_SIZE``: Maximum size of the GLOBAL 504 resource. Value type: ``uint64_t``. Shader IR type dependent. 505* ``PIPE_COMPUTE_CAP_MAX_LOCAL_SIZE``: Maximum size of the LOCAL 506 resource. Value type: ``uint64_t``. Shader IR type dependent. 507* ``PIPE_COMPUTE_CAP_MAX_PRIVATE_SIZE``: Maximum size of the PRIVATE 508 resource. Value type: ``uint64_t``. Shader IR type dependent. 509* ``PIPE_COMPUTE_CAP_MAX_INPUT_SIZE``: Maximum size of the INPUT 510 resource. Value type: ``uint64_t``. Shader IR type dependent. 511* ``PIPE_COMPUTE_CAP_MAX_MEM_ALLOC_SIZE``: Maximum size of a memory object 512 allocation in bytes. Value type: ``uint64_t``. 513* ``PIPE_COMPUTE_CAP_MAX_CLOCK_FREQUENCY``: Maximum frequency of the GPU 514 clock in MHz. Value type: ``uint32_t`` 515* ``PIPE_COMPUTE_CAP_MAX_COMPUTE_UNITS``: Maximum number of compute units 516 Value type: ``uint32_t`` 517* ``PIPE_COMPUTE_CAP_IMAGES_SUPPORTED``: Whether images are supported 518 non-zero means yes, zero means no. Value type: ``uint32_t`` 519* ``PIPE_COMPUTE_CAP_SUBGROUP_SIZE``: The size of a basic execution unit in 520 threads. Also known as wavefront size, warp size or SIMD width. 521* ``PIPE_COMPUTE_CAP_ADDRESS_BITS``: The default compute device address space 522 size specified as an unsigned integer value in bits. 523* ``PIPE_COMPUTE_CAP_MAX_VARIABLE_THREADS_PER_BLOCK``: Maximum variable number 524 of threads that a single block can contain. This is similar to 525 PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK, except that the variable size is not 526 known a compile-time but at dispatch-time. 527 528.. _pipe_bind: 529 530PIPE_BIND_* 531^^^^^^^^^^^ 532 533These flags indicate how a resource will be used and are specified at resource 534creation time. Resources may be used in different roles 535during their lifecycle. Bind flags are cumulative and may be combined to create 536a resource which can be used for multiple things. 537Depending on the pipe driver's memory management and these bind flags, 538resources might be created and handled quite differently. 539 540* ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be 541 rendered to. Any surface/resource attached to pipe_framebuffer_state::cbufs 542 must have this flag set. 543* ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any 544 depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must 545 have this flag set. 546* ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to 547 query whether a device supports blending for a given format. 548 If this flag is set, surface creation may fail if blending is not supported 549 for the specified format. If it is not set, a driver may choose to ignore 550 blending on surfaces with formats that would require emulation. 551* ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to 552 pipe_screen::flush_front_buffer must have this flag set. 553* ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment 554 or vertex shader. 555* ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer. 556* ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer. 557* ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants. 558* ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer. 559* ``PIPE_BIND_CUSTOM``: 560* ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer. 561* ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another 562 process. 563* ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global 564 address space of a compute program. 565* ``PIPE_BIND_SHADER_BUFFER``: A buffer without a format that can be bound 566 to a shader and can be used with load, store, and atomic instructions. 567* ``PIPE_BIND_SHADER_IMAGE``: A buffer or texture with a format that can be 568 bound to a shader and can be used with load, store, and atomic instructions. 569* ``PIPE_BIND_COMPUTE_RESOURCE``: A buffer or texture that can be 570 bound to the compute program as a shader resource. 571* ``PIPE_BIND_COMMAND_ARGS_BUFFER``: A buffer that may be sourced by the 572 GPU command processor. It can contain, for example, the arguments to 573 indirect draw calls. 574 575.. _pipe_usage: 576 577PIPE_USAGE_* 578^^^^^^^^^^^^ 579 580The PIPE_USAGE enums are hints about the expected usage pattern of a resource. 581Note that drivers must always support read and write CPU access at any time 582no matter which hint they got. 583 584* ``PIPE_USAGE_DEFAULT``: Optimized for fast GPU access. 585* ``PIPE_USAGE_IMMUTABLE``: Optimized for fast GPU access and the resource is 586 not expected to be mapped or changed (even by the GPU) after the first upload. 587* ``PIPE_USAGE_DYNAMIC``: Expect frequent write-only CPU access. What is 588 uploaded is expected to be used at least several times by the GPU. 589* ``PIPE_USAGE_STREAM``: Expect frequent write-only CPU access. What is 590 uploaded is expected to be used only once by the GPU. 591* ``PIPE_USAGE_STAGING``: Optimized for fast CPU access. 592 593 594Methods 595------- 596 597XXX to-do 598 599get_name 600^^^^^^^^ 601 602Returns an identifying name for the screen. 603 604get_vendor 605^^^^^^^^^^ 606 607Returns the screen vendor. 608 609get_device_vendor 610^^^^^^^^^^^^^^^^^ 611 612Returns the actual vendor of the device driving the screen 613(as opposed to the driver vendor). 614 615.. _get_param: 616 617get_param 618^^^^^^^^^ 619 620Get an integer/boolean screen parameter. 621 622**param** is one of the :ref:`PIPE_CAP` names. 623 624.. _get_paramf: 625 626get_paramf 627^^^^^^^^^^ 628 629Get a floating-point screen parameter. 630 631**param** is one of the :ref:`PIPE_CAP` names. 632 633context_create 634^^^^^^^^^^^^^^ 635 636Create a pipe_context. 637 638**priv** is private data of the caller, which may be put to various 639unspecified uses, typically to do with implementing swapbuffers 640and/or front-buffer rendering. 641 642is_format_supported 643^^^^^^^^^^^^^^^^^^^ 644 645Determine if a resource in the given format can be used in a specific manner. 646 647**format** the resource format 648 649**target** one of the PIPE_TEXTURE_x flags 650 651**sample_count** the number of samples. 0 and 1 mean no multisampling, 652the maximum allowed legal value is 32. 653 654**bindings** is a bitmask of :ref:`PIPE_BIND` flags. 655 656**geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags. 657 658Returns TRUE if all usages can be satisfied. 659 660 661can_create_resource 662^^^^^^^^^^^^^^^^^^^ 663 664Check if a resource can actually be created (but don't actually allocate any 665memory). This is used to implement OpenGL's proxy textures. Typically, a 666driver will simply check if the total size of the given resource is less than 667some limit. 668 669For PIPE_TEXTURE_CUBE, the pipe_resource::array_size field should be 6. 670 671 672.. _resource_create: 673 674resource_create 675^^^^^^^^^^^^^^^ 676 677Create a new resource from a template. 678The following fields of the pipe_resource must be specified in the template: 679 680**target** one of the pipe_texture_target enums. 681Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different. 682Modern APIs allow using buffers as shader resources. 683 684**format** one of the pipe_format enums. 685 686**width0** the width of the base mip level of the texture or size of the buffer. 687 688**height0** the height of the base mip level of the texture 689(1 for 1D or 1D array textures). 690 691**depth0** the depth of the base mip level of the texture 692(1 for everything else). 693 694**array_size** the array size for 1D and 2D array textures. 695For cube maps this must be 6, for other textures 1. 696 697**last_level** the last mip map level present. 698 699**nr_samples** the nr of msaa samples. 0 (or 1) specifies a resource 700which isn't multisampled. 701 702**usage** one of the PIPE_USAGE flags. 703 704**bind** bitmask of the PIPE_BIND flags. 705 706**flags** bitmask of PIPE_RESOURCE_FLAG flags. 707 708 709 710resource_destroy 711^^^^^^^^^^^^^^^^ 712 713Destroy a resource. A resource is destroyed if it has no more references. 714 715 716 717get_timestamp 718^^^^^^^^^^^^^ 719 720Query a timestamp in nanoseconds. The returned value should match 721PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't 722wait for rendering to complete (which cannot be achieved with queries). 723 724 725 726get_driver_query_info 727^^^^^^^^^^^^^^^^^^^^^ 728 729Return a driver-specific query. If the **info** parameter is NULL, 730the number of available queries is returned. Otherwise, the driver 731query at the specified **index** is returned in **info**. 732The function returns non-zero on success. 733The driver-specific query is described with the pipe_driver_query_info 734structure. 735 736get_driver_query_group_info 737^^^^^^^^^^^^^^^^^^^^^^^^^^^ 738 739Return a driver-specific query group. If the **info** parameter is NULL, 740the number of available groups is returned. Otherwise, the driver 741query group at the specified **index** is returned in **info**. 742The function returns non-zero on success. 743The driver-specific query group is described with the 744pipe_driver_query_group_info structure. 745 746 747Thread safety 748------------- 749 750Screen methods are required to be thread safe. While gallium rendering 751contexts are not required to be thread safe, it is required to be safe to use 752different contexts created with the same screen in different threads without 753locks. It is also required to be safe using screen methods in a thread, while 754using one of its contexts in another (without locks). 755