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_MAX_DUAL_SOURCE_RENDER_TARGETS``: How many dual-source blend RTs are support.
  28   :ref:`Blend` for more information.
  29 * ``PIPE_CAP_ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
  30 * ``PIPE_CAP_POINT_SPRITE``: Whether point sprites are available.
  31 * ``PIPE_CAP_MAX_RENDER_TARGETS``: The maximum number of render targets that may be
  32   bound.
  33 * ``PIPE_CAP_OCCLUSION_QUERY``: Whether occlusion queries are available.
  34 * ``PIPE_CAP_QUERY_TIME_ELAPSED``: Whether PIPE_QUERY_TIME_ELAPSED queries are available.
  35 * ``PIPE_CAP_TEXTURE_SWIZZLE``: Whether swizzling through sampler views is
  36   supported.
  37 * ``PIPE_CAP_MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
  38   for a 2D texture.
  39 * ``PIPE_CAP_MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
  40   for a 3D texture.
  41 * ``PIPE_CAP_MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
  42   for a cubemap.
  43 * ``PIPE_CAP_TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
  44   are supported.
  45 * ``PIPE_CAP_BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
  46   from color blend equations, in :ref:`Blend` state.
  47 * ``PIPE_CAP_SM3``: Whether the vertex shader and fragment shader support equivalent
  48   opcodes to the Shader Model 3 specification. XXX oh god this is horrible
  49 * ``PIPE_CAP_MAX_STREAM_OUTPUT_BUFFERS``: The maximum number of stream buffers.
  50 * ``PIPE_CAP_PRIMITIVE_RESTART``: Whether primitive restart is supported.
  51 * ``PIPE_CAP_INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
  52   masks are supported. If 0, then the first rendertarget's blend mask is
  53   replicated across all MRTs.
  54 * ``PIPE_CAP_INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
  55   available. If 0, then the first rendertarget's blend functions affect all
  56   MRTs.
  57 * ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS``: The maximum number of texture array
  58   layers supported. If 0, the array textures are not supported at all and
  59   the ARRAY texture targets are invalid.
  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.
  68 * ``PIPE_CAP_DEPTH_CLIP_DISABLE``: Whether the driver is capable of disabling
  69   depth clipping (through pipe_rasterizer_state)
  70 * ``PIPE_CAP_SHADER_STENCIL_EXPORT``: Whether a stencil reference value can be
  71   written from a fragment shader.
  72 * ``PIPE_CAP_TGSI_INSTANCEID``: Whether TGSI_SEMANTIC_INSTANCEID is supported
  73   in the vertex shader.
  74 * ``PIPE_CAP_VERTEX_ELEMENT_INSTANCE_DIVISOR``: Whether the driver supports
  75   per-instance vertex attribs.
  76 * ``PIPE_CAP_FRAGMENT_COLOR_CLAMPED``: Whether fragment color clamping is
  77   supported.  That is, is the pipe_rasterizer_state::clamp_fragment_color
  78   flag supported by the driver?  If not, the state tracker will insert
  79   clamping code into the fragment shaders when needed.
  80
  81 * ``PIPE_CAP_MIXED_COLORBUFFER_FORMATS``: Whether mixed colorbuffer formats are
  82   supported, e.g. RGBA8 and RGBA32F as the first and second colorbuffer, resp.
  83 * ``PIPE_CAP_VERTEX_COLOR_UNCLAMPED``: Whether the driver is capable of
  84   outputting unclamped vertex colors from a vertex shader. If unsupported,
  85   the vertex colors are always clamped. This is the default for DX9 hardware.
  86 * ``PIPE_CAP_VERTEX_COLOR_CLAMPED``: Whether the driver is capable of
  87   clamping vertex colors when they come out of a vertex shader, as specified
  88   by the pipe_rasterizer_state::clamp_vertex_color flag.  If unsupported,
  89   the vertex colors are never clamped. This is the default for DX10 hardware.
  90   If both clamped and unclamped CAPs are supported, the clamping can be
  91   controlled through pipe_rasterizer_state.  If the driver cannot do vertex
  92   color clamping, the state tracker may insert clamping code into the vertex
  93   shader.
  94 * ``PIPE_CAP_GLSL_FEATURE_LEVEL``: Whether the driver supports features
  95   equivalent to a specific GLSL version. E.g. for GLSL 1.3, report 130.
  96 * ``PIPE_CAP_GLSL_FEATURE_LEVEL_COMPATIBILITY``: Whether the driver supports
  97   features equivalent to a specific GLSL version including all legacy OpenGL
  98   features only present in the OpenGL compatibility profile.
  99   The only legacy features that Gallium drivers must implement are
 100   the legacy shader inputs and outputs (colors, texcoords, fog, clipvertex,
 101   edgeflag).
 102 * ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION``: Whether quads adhere to
 103   the flatshade_first setting in ``pipe_rasterizer_state``.
 104 * ``PIPE_CAP_USER_VERTEX_BUFFERS``: Whether the driver supports user vertex
 105   buffers.  If not, the state tracker must upload all data which is not in hw
 106   resources.  If user-space buffers are supported, the driver must also still
 107   accept HW resource buffers.
 108 * ``PIPE_CAP_VERTEX_BUFFER_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
 109   limitation.  If true, pipe_vertex_buffer::buffer_offset must always be aligned
 110   to 4.  If false, there are no restrictions on the offset.
 111 * ``PIPE_CAP_VERTEX_BUFFER_STRIDE_4BYTE_ALIGNED_ONLY``: This CAP describes a hw
 112   limitation.  If true, pipe_vertex_buffer::stride must always be aligned to 4.
 113   If false, there are no restrictions on the stride.
 114 * ``PIPE_CAP_VERTEX_ELEMENT_SRC_OFFSET_4BYTE_ALIGNED_ONLY``: This CAP describes
 115   a hw limitation.  If true, pipe_vertex_element::src_offset must always be
 116   aligned to 4.  If false, there are no restrictions on src_offset.
 117 * ``PIPE_CAP_COMPUTE``: Whether the implementation supports the
 118   compute entry points defined in pipe_context and pipe_screen.
 119 * ``PIPE_CAP_CONSTANT_BUFFER_OFFSET_ALIGNMENT``: Describes the required
 120   alignment of pipe_constant_buffer::buffer_offset.
 121 * ``PIPE_CAP_START_INSTANCE``: Whether the driver supports
 122   pipe_draw_info::start_instance.
 123 * ``PIPE_CAP_QUERY_TIMESTAMP``: Whether PIPE_QUERY_TIMESTAMP and
 124   the pipe_screen::get_timestamp hook are implemented.
 125 * ``PIPE_CAP_TEXTURE_MULTISAMPLE``: Whether all MSAA resources supported
 126   for rendering are also supported for texturing.
 127 * ``PIPE_CAP_MIN_MAP_BUFFER_ALIGNMENT``: The minimum alignment that should be
 128   expected for a pointer returned by transfer_map if the resource is
 129   PIPE_BUFFER. In other words, the pointer returned by transfer_map is
 130   always aligned to this value.
 131 * ``PIPE_CAP_TEXTURE_BUFFER_OFFSET_ALIGNMENT``: Describes the required
 132   alignment for pipe_sampler_view::u.buf.offset, in bytes.
 133   If a driver does not support offset/size, it should return 0.
 134 * ``PIPE_CAP_BUFFER_SAMPLER_VIEW_RGBA_ONLY``: Whether the driver only
 135   supports R, RG, RGB and RGBA formats for PIPE_BUFFER sampler views.
 136   When this is the case it should be assumed that the swizzle parameters
 137   in the sampler view have no effect.
 138 * ``PIPE_CAP_TGSI_TEXCOORD``: This CAP describes a hw limitation.
 139   If true, the hardware cannot replace arbitrary shader inputs with sprite
 140   coordinates and hence the inputs that are desired to be replaceable must
 141   be declared with TGSI_SEMANTIC_TEXCOORD instead of TGSI_SEMANTIC_GENERIC.
 142   The rasterizer's sprite_coord_enable state therefore also applies to the
 143   TEXCOORD semantic.
 144   Also, TGSI_SEMANTIC_PCOORD becomes available, which labels a fragment shader
 145   input that will always be replaced with sprite coordinates.
 146 * ``PIPE_CAP_PREFER_BLIT_BASED_TEXTURE_TRANSFER``: Whether it is preferable
 147   to use a blit to implement a texture transfer which needs format conversions
 148   and swizzling in state trackers. Generally, all hardware drivers with
 149   dedicated memory should return 1 and all software rasterizers should return 0.
 150 * ``PIPE_CAP_QUERY_PIPELINE_STATISTICS``: Whether PIPE_QUERY_PIPELINE_STATISTICS
 151   is supported.
 152 * ``PIPE_CAP_TEXTURE_BORDER_COLOR_QUIRK``: Bitmask indicating whether special
 153   considerations have to be given to the interaction between the border color
 154   in the sampler object and the sampler view used with it.
 155   If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_R600 is set, the border color
 156   may be affected in undefined ways for any kind of permutational swizzle
 157   (any swizzle XYZW where X/Y/Z/W are not ZERO, ONE, or R/G/B/A respectively)
 158   in the sampler view.
 159   If PIPE_QUIRK_TEXTURE_BORDER_COLOR_SWIZZLE_NV50 is set, the border color
 160   state should be swizzled manually according to the swizzle in the sampler
 161   view it is intended to be used with, or herein undefined results may occur
 162   for permutational swizzles.
 163 * ``PIPE_CAP_MAX_TEXTURE_BUFFER_SIZE``: The maximum accessible size with
 164   a buffer sampler view, in texels.
 165 * ``PIPE_CAP_MAX_VIEWPORTS``: The maximum number of viewports (and scissors
 166   since they are linked) a driver can support. Returning 0 is equivalent
 167   to returning 1 because every driver has to support at least a single
 168   viewport/scissor combination.
 169 * ``PIPE_CAP_ENDIANNESS``:: The endianness of the device.  Either
 170   PIPE_ENDIAN_BIG or PIPE_ENDIAN_LITTLE.
 171 * ``PIPE_CAP_MIXED_FRAMEBUFFER_SIZES``: Whether it is allowed to have
 172   different sizes for fb color/zs attachments. This controls whether
 173   ARB_framebuffer_object is provided.
 174 * ``PIPE_CAP_TGSI_VS_LAYER_VIEWPORT``: Whether ``TGSI_SEMANTIC_LAYER`` and
 175   ``TGSI_SEMANTIC_VIEWPORT_INDEX`` are supported as vertex shader
 176   outputs. Note that the viewport will only be used if multiple viewports are
 177   exposed.
 178 * ``PIPE_CAP_MAX_GEOMETRY_OUTPUT_VERTICES``: The maximum number of vertices
 179   output by a single invocation of a geometry shader.
 180 * ``PIPE_CAP_MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS``: The maximum number of
 181   vertex components output by a single invocation of a geometry shader.
 182   This is the product of the number of attribute components per vertex and
 183   the number of output vertices.
 184 * ``PIPE_CAP_MAX_TEXTURE_GATHER_COMPONENTS``: Max number of components
 185   in format that texture gather can operate on. 1 == RED, ALPHA etc,
 186   4 == All formats.
 187 * ``PIPE_CAP_TEXTURE_GATHER_SM5``: Whether the texture gather
 188   hardware implements the SM5 features, component selection,
 189   shadow comparison, and run-time offsets.
 190 * ``PIPE_CAP_BUFFER_MAP_PERSISTENT_COHERENT``: Whether
 191   PIPE_TRANSFER_PERSISTENT and PIPE_TRANSFER_COHERENT are supported
 192   for buffers.
 193 * ``PIPE_CAP_TEXTURE_QUERY_LOD``: Whether the ``LODQ`` instruction is
 194   supported.
 195 * ``PIPE_CAP_MIN_TEXTURE_GATHER_OFFSET``: The minimum offset that can be used
 196   in conjunction with a texture gather opcode.
 197 * ``PIPE_CAP_MAX_TEXTURE_GATHER_OFFSET``: The maximum offset that can be used
 198   in conjunction with a texture gather opcode.
 199 * ``PIPE_CAP_SAMPLE_SHADING``: Whether there is support for per-sample
 200   shading. The context->set_min_samples function will be expected to be
 201   implemented.
 202 * ``PIPE_CAP_TEXTURE_GATHER_OFFSETS``: Whether the ``TG4`` instruction can
 203   accept 4 offsets.
 204 * ``PIPE_CAP_TGSI_VS_WINDOW_SPACE_POSITION``: Whether
 205   TGSI_PROPERTY_VS_WINDOW_SPACE_POSITION is supported, which disables clipping
 206   and viewport transformation.
 207 * ``PIPE_CAP_MAX_VERTEX_STREAMS``: The maximum number of vertex streams
 208   supported by the geometry shader. If stream-out is supported, this should be
 209   at least 1. If stream-out is not supported, this should be 0.
 210 * ``PIPE_CAP_DRAW_INDIRECT``: Whether the driver supports taking draw arguments
 211   { count, instance_count, start, index_bias } from a PIPE_BUFFER resource.
 212   See pipe_draw_info.
 213 * ``PIPE_CAP_MULTI_DRAW_INDIRECT``: Whether the driver supports
 214   pipe_draw_info::indirect_stride and ::indirect_count
 215 * ``PIPE_CAP_MULTI_DRAW_INDIRECT_PARAMS``: Whether the driver supports
 216   taking the number of indirect draws from a separate parameter
 217   buffer, see pipe_draw_indirect_info::indirect_draw_count.
 218 * ``PIPE_CAP_TGSI_FS_FINE_DERIVATIVE``: Whether the fragment shader supports
 219   the FINE versions of DDX/DDY.
 220 * ``PIPE_CAP_VENDOR_ID``: The vendor ID of the underlying hardware. If it's
 221   not available one should return 0xFFFFFFFF.
 222 * ``PIPE_CAP_DEVICE_ID``: The device ID (PCI ID) of the underlying hardware.
 223   0xFFFFFFFF if not available.
 224 * ``PIPE_CAP_ACCELERATED``: Whether the renderer is hardware accelerated.
 225 * ``PIPE_CAP_VIDEO_MEMORY``: The amount of video memory in megabytes.
 226 * ``PIPE_CAP_UMA``: If the device has a unified memory architecture or on-card
 227   memory and GART.
 228 * ``PIPE_CAP_CONDITIONAL_RENDER_INVERTED``: Whether the driver supports inverted
 229   condition for conditional rendering.
 230 * ``PIPE_CAP_MAX_VERTEX_ATTRIB_STRIDE``: The maximum supported vertex stride.
 231 * ``PIPE_CAP_SAMPLER_VIEW_TARGET``: Whether the sampler view's target can be
 232   different than the underlying resource's, as permitted by
 233   ARB_texture_view. For example a 2d array texture may be reinterpreted as a
 234   cube (array) texture and vice-versa.
 235 * ``PIPE_CAP_CLIP_HALFZ``: Whether the driver supports the
 236   pipe_rasterizer_state::clip_halfz being set to true. This is required
 237   for enabling ARB_clip_control.
 238 * ``PIPE_CAP_VERTEXID_NOBASE``: If true, the driver only supports
 239   TGSI_SEMANTIC_VERTEXID_NOBASE (and not TGSI_SEMANTIC_VERTEXID). This means
 240   state trackers for APIs whose vertexIDs are offset by basevertex (such as GL)
 241   will need to lower TGSI_SEMANTIC_VERTEXID to TGSI_SEMANTIC_VERTEXID_NOBASE
 242   and TGSI_SEMANTIC_BASEVERTEX, so drivers setting this must handle both these
 243   semantics. Only relevant if geometry shaders are supported.
 244   (BASEVERTEX could be exposed separately too via ``PIPE_CAP_DRAW_PARAMETERS``).
 245 * ``PIPE_CAP_POLYGON_OFFSET_CLAMP``: If true, the driver implements support
 246   for ``pipe_rasterizer_state::offset_clamp``.
 247 * ``PIPE_CAP_MULTISAMPLE_Z_RESOLVE``: Whether the driver supports blitting
 248   a multisampled depth buffer into a single-sampled texture (or depth buffer).
 249   Only the first sampled should be copied.
 250 * ``PIPE_CAP_RESOURCE_FROM_USER_MEMORY``: Whether the driver can create
 251   a pipe_resource where an already-existing piece of (malloc'd) user memory
 252   is used as its backing storage. In other words, whether the driver can map
 253   existing user memory into the device address space for direct device access.
 254   The create function is pipe_screen::resource_from_user_memory. The address
 255   and size must be page-aligned.
 256 * ``PIPE_CAP_DEVICE_RESET_STATUS_QUERY``:
 257   Whether pipe_context::get_device_reset_status is implemented.
 258 * ``PIPE_CAP_MAX_SHADER_PATCH_VARYINGS``:
 259   How many per-patch outputs and inputs are supported between tessellation
 260   control and tessellation evaluation shaders, not counting in TESSINNER and
 261   TESSOUTER. The minimum allowed value for OpenGL is 30.
 262 * ``PIPE_CAP_TEXTURE_FLOAT_LINEAR``: Whether the linear minification and
 263   magnification filters are supported with single-precision floating-point
 264   textures.
 265 * ``PIPE_CAP_TEXTURE_HALF_FLOAT_LINEAR``: Whether the linear minification and
 266   magnification filters are supported with half-precision floating-point
 267   textures.
 268 * ``PIPE_CAP_DEPTH_BOUNDS_TEST``: Whether bounds_test, bounds_min, and
 269   bounds_max states of pipe_depth_stencil_alpha_state behave according
 270   to the GL_EXT_depth_bounds_test specification.
 271 * ``PIPE_CAP_TGSI_TXQS``: Whether the `TXQS` opcode is supported
 272 * ``PIPE_CAP_FORCE_PERSAMPLE_INTERP``: If the driver can force per-sample
 273   interpolation for all fragment shader inputs if
 274   pipe_rasterizer_state::force_persample_interp is set. This is only used
 275   by GL3-level sample shading (ARB_sample_shading). GL4-level sample shading
 276   (ARB_gpu_shader5) doesn't use this. While GL3 hardware has a state for it,
 277   GL4 hardware will likely need to emulate it with a shader variant, or by
 278   selecting the interpolation weights with a conditional assignment
 279   in the shader.
 280 * ``PIPE_CAP_SHAREABLE_SHADERS``: Whether shader CSOs can be used by any
 281   pipe_context.
 282 * ``PIPE_CAP_COPY_BETWEEN_COMPRESSED_AND_PLAIN_FORMATS``:
 283   Whether copying between compressed and plain formats is supported where
 284   a compressed block is copied to/from a plain pixel of the same size.
 285 * ``PIPE_CAP_CLEAR_TEXTURE``: Whether `clear_texture` will be
 286   available in contexts.
 287 * ``PIPE_CAP_DRAW_PARAMETERS``: Whether ``TGSI_SEMANTIC_BASEVERTEX``,
 288   ``TGSI_SEMANTIC_BASEINSTANCE``, and ``TGSI_SEMANTIC_DRAWID`` are
 289   supported in vertex shaders.
 290 * ``PIPE_CAP_TGSI_PACK_HALF_FLOAT``: Whether the ``UP2H`` and ``PK2H``
 291   TGSI opcodes are supported.
 292 * ``PIPE_CAP_TGSI_FS_POSITION_IS_SYSVAL``: If state trackers should use
 293   a system value for the POSITION fragment shader input.
 294 * ``PIPE_CAP_TGSI_FS_FACE_IS_INTEGER_SYSVAL``: If state trackers should use
 295   a system value for the FACE fragment shader input.
 296   Also, the FACE system value is integer, not float.
 297 * ``PIPE_CAP_SHADER_BUFFER_OFFSET_ALIGNMENT``: Describes the required
 298   alignment for pipe_shader_buffer::buffer_offset, in bytes. Maximum
 299   value allowed is 256 (for GL conformance). 0 is only allowed if
 300   shader buffers are not supported.
 301 * ``PIPE_CAP_INVALIDATE_BUFFER``: Whether the use of ``invalidate_resource``
 302   for buffers is supported.
 303 * ``PIPE_CAP_GENERATE_MIPMAP``: Indicates whether pipe_context::generate_mipmap
 304   is supported.
 305 * ``PIPE_CAP_STRING_MARKER``: Whether pipe->emit_string_marker() is supported.
 306 * ``PIPE_CAP_SURFACE_REINTERPRET_BLOCKS``: Indicates whether
 307   pipe_context::create_surface supports reinterpreting a texture as a surface
 308   of a format with different block width/height (but same block size in bits).
 309   For example, a compressed texture image can be interpreted as a
 310   non-compressed surface whose texels are the same number of bits as the
 311   compressed blocks, and vice versa. The width and height of the surface is
 312   adjusted appropriately.
 313 * ``PIPE_CAP_QUERY_BUFFER_OBJECT``: Driver supports
 314   context::get_query_result_resource callback.
 315 * ``PIPE_CAP_PCI_GROUP``: Return the PCI segment group number.
 316 * ``PIPE_CAP_PCI_BUS``: Return the PCI bus number.
 317 * ``PIPE_CAP_PCI_DEVICE``: Return the PCI device number.
 318 * ``PIPE_CAP_PCI_FUNCTION``: Return the PCI function number.
 319 * ``PIPE_CAP_FRAMEBUFFER_NO_ATTACHMENT``:
 320   If non-zero, rendering to framebuffers with no surface attachments
 321   is supported. The context->is_format_supported function will be expected
 322   to be implemented with PIPE_FORMAT_NONE yeilding the MSAA modes the hardware
 323   supports. N.B., The maximum number of layers supported for rasterizing a
 324   primitive on a layer is obtained from ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS``
 325   even though it can be larger than the number of layers supported by either
 326   rendering or textures.
 327 * ``PIPE_CAP_ROBUST_BUFFER_ACCESS_BEHAVIOR``: Implementation uses bounds
 328   checking on resource accesses by shader if the context is created with
 329   PIPE_CONTEXT_ROBUST_BUFFER_ACCESS. See the ARB_robust_buffer_access_behavior
 330   extension for information on the required behavior for out of bounds accesses
 331   and accesses to unbound resources.
 332 * ``PIPE_CAP_CULL_DISTANCE``: Whether the driver supports the arb_cull_distance
 333   extension and thus implements proper support for culling planes.
 334 * ``PIPE_CAP_PRIMITIVE_RESTART_FOR_PATCHES``: Whether primitive restart is
 335   supported for patch primitives.
 336 * ``PIPE_CAP_TGSI_VOTE``: Whether the ``VOTE_*`` ops can be used in shaders.
 337 * ``PIPE_CAP_MAX_WINDOW_RECTANGLES``: The maxium number of window rectangles
 338   supported in ``set_window_rectangles``.
 339 * ``PIPE_CAP_POLYGON_OFFSET_UNITS_UNSCALED``: If true, the driver implements support
 340   for ``pipe_rasterizer_state::offset_units_unscaled``.
 341 * ``PIPE_CAP_VIEWPORT_SUBPIXEL_BITS``: Number of bits of subpixel precision for
 342   floating point viewport bounds.
 343 * ``PIPE_CAP_MIXED_COLOR_DEPTH_BITS``: Whether there is non-fallback
 344   support for color/depth format combinations that use a different
 345   number of bits. For the purpose of this cap, Z24 is treated as
 346   32-bit. If set to off, that means that a B5G6R5 + Z24 or RGBA8 + Z16
 347   combination will require a driver fallback, and should not be
 348   advertised in the GLX/EGL config list.
 349 * ``PIPE_CAP_TGSI_ARRAY_COMPONENTS``: If true, the driver interprets the
 350   UsageMask of input and output declarations and allows declaring arrays
 351   in overlapping ranges. The components must be a contiguous range, e.g. a
 352   UsageMask of  xy or yzw is allowed, but xz or yw isn't. Declarations with
 353   overlapping locations must have matching semantic names and indices, and
 354   equal interpolation qualifiers.
 355   Components may overlap, notably when the gaps in an array of dvec3 are
 356   filled in.
 357 * ``PIPE_CAP_STREAM_OUTPUT_INTERLEAVE_BUFFERS``: Whether interleaved stream
 358   output mode is able to interleave across buffers. This is required for
 359   ARB_transform_feedback3.
 360 * ``PIPE_CAP_TGSI_CAN_READ_OUTPUTS``: Whether every TGSI shader stage can read
 361   from the output file.
 362 * ``PIPE_CAP_GLSL_OPTIMIZE_CONSERVATIVELY``: Tell the GLSL compiler to use
 363   the minimum amount of optimizations just to be able to do all the linking
 364   and lowering.
 365 * ``PIPE_CAP_TGSI_FS_FBFETCH``: Whether a fragment shader can use the FBFETCH
 366   opcode to retrieve the current value in the framebuffer.
 367 * ``PIPE_CAP_TGSI_MUL_ZERO_WINS``: Whether TGSI shaders support the
 368   ``TGSI_PROPERTY_MUL_ZERO_WINS`` shader property.
 369 * ``PIPE_CAP_DOUBLES``: Whether double precision floating-point operations
 370   are supported.
 371 * ``PIPE_CAP_INT64``: Whether 64-bit integer operations are supported.
 372 * ``PIPE_CAP_INT64_DIVMOD``: Whether 64-bit integer division/modulo
 373   operations are supported.
 374 * ``PIPE_CAP_TGSI_TEX_TXF_LZ``: Whether TEX_LZ and TXF_LZ opcodes are
 375   supported.
 376 * ``PIPE_CAP_TGSI_CLOCK``: Whether the CLOCK opcode is supported.
 377 * ``PIPE_CAP_POLYGON_MODE_FILL_RECTANGLE``: Whether the
 378   PIPE_POLYGON_MODE_FILL_RECTANGLE mode is supported for
 379   ``pipe_rasterizer_state::fill_front`` and
 380   ``pipe_rasterizer_state::fill_back``.
 381 * ``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``: The page size of sparse buffers in
 382   bytes, or 0 if sparse buffers are not supported. The page size must be at
 383   most 64KB.
 384 * ``PIPE_CAP_TGSI_BALLOT``: Whether the BALLOT and READ_* opcodes as well as
 385   the SUBGROUP_* semantics are supported.
 386 * ``PIPE_CAP_TGSI_TES_LAYER_VIEWPORT``: Whether ``TGSI_SEMANTIC_LAYER`` and
 387   ``TGSI_SEMANTIC_VIEWPORT_INDEX`` are supported as tessellation evaluation
 388   shader outputs.
 389 * ``PIPE_CAP_CAN_BIND_CONST_BUFFER_AS_VERTEX``: Whether a buffer with just
 390   PIPE_BIND_CONSTANT_BUFFER can be legally passed to set_vertex_buffers.
 391 * ``PIPE_CAP_ALLOW_MAPPED_BUFFERS_DURING_EXECUTION``: As the name says.
 392 * ``PIPE_CAP_POST_DEPTH_COVERAGE``: whether
 393   ``TGSI_PROPERTY_FS_POST_DEPTH_COVERAGE`` is supported.
 394 * ``PIPE_CAP_BINDLESS_TEXTURE``: Whether bindless texture operations are
 395   supported.
 396 * ``PIPE_CAP_NIR_SAMPLERS_AS_DEREF``: Whether NIR tex instructions should
 397   reference texture and sampler as NIR derefs instead of by indices.
 398 * ``PIPE_CAP_QUERY_SO_OVERFLOW``: Whether the
 399   ``PIPE_QUERY_SO_OVERFLOW_PREDICATE`` and
 400   ``PIPE_QUERY_SO_OVERFLOW_ANY_PREDICATE`` query types are supported. Note that
 401   for a driver that does not support multiple output streams (i.e.,
 402   ``PIPE_CAP_MAX_VERTEX_STREAMS`` is 1), both query types are identical.
 403 * ``PIPE_CAP_MEMOBJ``: Whether operations on memory objects are supported.
 404 * ``PIPE_CAP_LOAD_CONSTBUF``: True if the driver supports TGSI_OPCODE_LOAD use
 405   with constant buffers.
 406 * ``PIPE_CAP_TGSI_ANY_REG_AS_ADDRESS``: Any TGSI register can be used as
 407   an address for indirect register indexing.
 408 * ``PIPE_CAP_TILE_RASTER_ORDER``: Whether the driver supports
 409   GL_MESA_tile_raster_order, using the tile_raster_order_* fields in
 410   pipe_rasterizer_state.
 411 * ``PIPE_CAP_MAX_COMBINED_SHADER_OUTPUT_RESOURCES``: Limit on combined shader
 412   output resources (images + buffers + fragment outputs). If 0 the state
 413   tracker works it out.
 414 * ``PIPE_CAP_FRAMEBUFFER_MSAA_CONSTRAINTS``: This determines limitations
 415   on the number of samples that framebuffer attachments can have.
 416   Possible values:
 417     0: color.nr_samples == zs.nr_samples == color.nr_storage_samples
 418        (standard MSAA quality)
 419     1: color.nr_samples >= zs.nr_samples == color.nr_storage_samples
 420        (enhanced MSAA quality)
 421     2: color.nr_samples >= zs.nr_samples >= color.nr_storage_samples
 422        (full flexibility in tuning MSAA quality and performance)
 423   All color attachments must have the same number of samples and the same
 424   number of storage samples.
 425 * ``PIPE_CAP_SIGNED_VERTEX_BUFFER_OFFSET``:
 426   Whether pipe_vertex_buffer::buffer_offset is treated as signed. The u_vbuf
 427   module needs this for optimal performance in workstation applications.
 428 * ``PIPE_CAP_CONTEXT_PRIORITY_MASK``: For drivers that support per-context
 429   priorities, this returns a bitmask of PIPE_CONTEXT_PRIORITY_x for the
 430   supported priority levels.  A driver that does not support prioritized
 431   contexts can return 0.
 432 * ``PIPE_CAP_FENCE_SIGNAL``: True if the driver supports signaling semaphores
 433   using fence_server_signal().
 434 * ``PIPE_CAP_CONSTBUF0_FLAGS``: The bits of pipe_resource::flags that must be
 435   set when binding that buffer as constant buffer 0. If the buffer doesn't have
 436   those bits set, pipe_context::set_constant_buffer(.., 0, ..) is ignored
 437   by the driver, and the driver can throw assertion failures.
 438 * ``PIPE_CAP_PACKED_UNIFORMS``: True if the driver supports packed uniforms
 439   as opposed to padding to vec4s.
 440 * ``PIPE_CAP_CONSERVATIVE_RASTER_POST_SNAP_TRIANGLES``: Whether the
 441   PIPE_CONSERVATIVE_RASTER_POST_SNAP mode is supported for triangles.
 442 * ``PIPE_CAP_CONSERVATIVE_RASTER_POST_SNAP_POINTS_LINES``: Whether the
 443 PIPE_CONSERVATIVE_RASTER_POST_SNAP mode is supported for points and lines.
 444 * ``PIPE_CAP_CONSERVATIVE_RASTER_PRE_SNAP_TRIANGLES``: Whether the
 445 PIPE_CONSERVATIVE_RASTER_PRE_SNAP mode is supported for triangles.
 446 * ``PIPE_CAP_CONSERVATIVE_RASTER_PRE_SNAP_POINTS_LINES``: Whether the
 447 PIPE_CONSERVATIVE_RASTER_PRE_SNAP mode is supported for points and lines.
 448 * ``PIPE_CAP_CONSERVATIVE_RASTER_POST_DEPTH_COVERAGE``: Whether PIPE_CAP_POST_DEPTH_COVERAGE
 449 works with conservative rasterization.
 450 * ``PIPE_CAP_MAX_CONSERVATIVE_RASTER_SUBPIXEL_PRECISION_BIAS``: The maximum
 451 subpixel precision bias in bits during conservative rasterization.
 452 * ``PIPE_CAP_PROGRAMMABLE_SAMPLE_LOCATIONS``: True is the driver supports
 453   programmable sample location through ```get_sample_pixel_grid``` and
 454   ```set_sample_locations```.
 455 * ``PIPE_CAP_MAX_GS_INVOCATIONS``: Maximum supported value of
 456   TGSI_PROPERTY_GS_INVOCATIONS.
 457
 458 .. _pipe_capf:
 459
 460 PIPE_CAPF_*
 461 ^^^^^^^^^^^^^^^^
 462
 463 The floating-point capabilities are:
 464
 465 * ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line.
 466 * ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
 467 * ``PIPE_CAPF_MAX_POINT_WIDTH``: The maximum width and height of a point.
 468 * ``PIPE_CAPF_MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
 469 * ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
 470   applied to anisotropically filtered textures.
 471 * ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
 472   to filtered textures.
 473 * ``PIPE_CAPF_MIN_CONSERVATIVE_RASTER_DILATE``: The minimum conservative rasterization
 474   dilation.
 475 * ``PIPE_CAPF_MAX_CONSERVATIVE_RASTER_DILATE``: The maximum conservative rasterization
 476   dilation.
 477 * ``PIPE_CAPF_CONSERVATIVE_RASTER_DILATE_GRANULARITY``: The conservative rasterization
 478   dilation granularity for values relative to the minimum dilation.
 479
 480
 481 .. _pipe_shader_cap:
 482
 483 PIPE_SHADER_CAP_*
 484 ^^^^^^^^^^^^^^^^^
 485
 486 These are per-shader-stage capabitity queries. Different shader stages may
 487 support different features.
 488
 489 * ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions.
 490 * ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
 491 * ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
 492 * ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections.
 493 * ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
 494 * ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers.
 495 * ``PIPE_SHADER_CAP_MAX_OUTPUTS``: The maximum number of output registers.
 496   This is valid for all shaders except the fragment shader.
 497 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFER_SIZE``: The maximum size per constant buffer in bytes.
 498 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
 499   to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
 500   only permit binding one constant buffer per shader.
 501
 502 If a value greater than 0 is returned, the driver can have multiple
 503 constant buffers bound to shader stages. The CONST register file is
 504 accessed with two-dimensional indices, like in the example below.
 505
 506 DCL CONST[0][0..7]       # declare first 8 vectors of constbuf 0
 507 DCL CONST[3][0]          # declare first vector of constbuf 3
 508 MOV OUT[0], CONST[0][3]  # copy vector 3 of constbuf 0
 509
 510 * ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers.
 511 * ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported.
 512 * ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing
 513   of the input file is supported.
 514 * ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing
 515   of the output file is supported.
 516 * ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing
 517   of the temporary file is supported.
 518 * ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing
 519   of the constant file is supported.
 520 * ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e.
 521   BGNSUB, ENDSUB, CAL, and RET, including RET in the main block.
 522 * ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported.
 523   If unsupported, only float opcodes are supported.
 524 * ``PIPE_SHADER_CAP_INT64_ATOMICS``: Whether int64 atomic opcodes are supported. The device needs to support add, sub, swap, cmpswap, and, or, xor, min, and max.
 525 * ``PIPE_SHADER_CAP_FP16``: Whether half precision floating-point opcodes are supported.
 526    If unsupported, half precision ops need to be lowered to full precision.
 527 * ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: The maximum number of texture
 528   samplers.
 529 * ``PIPE_SHADER_CAP_PREFERRED_IR``: Preferred representation of the
 530   program.  It should be one of the ``pipe_shader_ir`` enum values.
 531 * ``PIPE_SHADER_CAP_MAX_SAMPLER_VIEWS``: The maximum number of texture
 532   sampler views. Must not be lower than PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS.
 533 * ``PIPE_SHADER_CAP_TGSI_DROUND_SUPPORTED``: Whether double precision rounding
 534   is supported. If it is, DTRUNC/DCEIL/DFLR/DROUND opcodes may be used.
 535 * ``PIPE_SHADER_CAP_TGSI_DFRACEXP_DLDEXP_SUPPORTED``: Whether DFRACEXP and
 536   DLDEXP are supported.
 537 * ``PIPE_SHADER_CAP_TGSI_LDEXP_SUPPORTED``: Whether LDEXP is supported.
 538 * ``PIPE_SHADER_CAP_TGSI_FMA_SUPPORTED``: Whether FMA and DFMA (doubles only)
 539   are supported.
 540 * ``PIPE_SHADER_CAP_TGSI_ANY_INOUT_DECL_RANGE``: Whether the driver doesn't
 541   ignore tgsi_declaration_range::Last for shader inputs and outputs.
 542 * ``PIPE_SHADER_CAP_MAX_UNROLL_ITERATIONS_HINT``: This is the maximum number
 543   of iterations that loops are allowed to have to be unrolled. It is only
 544   a hint to state trackers. Whether any loops will be unrolled is not
 545   guaranteed.
 546 * ``PIPE_SHADER_CAP_MAX_SHADER_BUFFERS``: Maximum number of memory buffers
 547   (also used to implement atomic counters). Having this be non-0 also
 548   implies support for the ``LOAD``, ``STORE``, and ``ATOM*`` TGSI
 549   opcodes.
 550 * ``PIPE_SHADER_CAP_SUPPORTED_IRS``: Supported representations of the
 551   program.  It should be a mask of ``pipe_shader_ir`` bits.
 552 * ``PIPE_SHADER_CAP_MAX_SHADER_IMAGES``: Maximum number of image units.
 553 * ``PIPE_SHADER_CAP_LOWER_IF_THRESHOLD``: IF and ELSE branches with a lower
 554   cost than this value should be lowered by the state tracker for better
 555   performance. This is a tunable for the GLSL compiler and the behavior is
 556   specific to the compiler.
 557 * ``PIPE_SHADER_CAP_TGSI_SKIP_MERGE_REGISTERS``: Whether the merge registers
 558   TGSI pass is skipped. This might reduce code size and register pressure if
 559   the underlying driver has a real backend compiler.
 560 * ``PIPE_SHADER_CAP_MAX_HW_ATOMIC_COUNTERS``: If atomic counters are separate,
 561   how many HW counters are available for this stage. (0 uses SSBO atomics).
 562 * ``PIPE_SHADER_CAP_MAX_HW_ATOMIC_COUNTER_BUFFERS``: If atomic counters are
 563   separate, how many atomic counter buffers are available for this stage.
 564 * ``PIPE_SHADER_CAP_SCALAR_ISA``: Whether the ISA is a scalar one.
 565
 566 .. _pipe_compute_cap:
 567
 568 PIPE_COMPUTE_CAP_*
 569 ^^^^^^^^^^^^^^^^^^
 570
 571 Compute-specific capabilities. They can be queried using
 572 pipe_screen::get_compute_param.
 573
 574 * ``PIPE_COMPUTE_CAP_IR_TARGET``: A description of the target of the form
 575   ``processor-arch-manufacturer-os`` that will be passed on to the compiler.
 576   This CAP is only relevant for drivers that specify PIPE_SHADER_IR_NATIVE for
 577   their preferred IR.
 578   Value type: null-terminated string. Shader IR type dependent.
 579 * ``PIPE_COMPUTE_CAP_GRID_DIMENSION``: Number of supported dimensions
 580   for grid and block coordinates.  Value type: ``uint64_t``. Shader IR type dependent.
 581 * ``PIPE_COMPUTE_CAP_MAX_GRID_SIZE``: Maximum grid size in block
 582   units.  Value type: ``uint64_t []``.  Shader IR type dependent.
 583 * ``PIPE_COMPUTE_CAP_MAX_BLOCK_SIZE``: Maximum block size in thread
 584   units.  Value type: ``uint64_t []``. Shader IR type dependent.
 585 * ``PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK``: Maximum number of threads that
 586   a single block can contain.  Value type: ``uint64_t``. Shader IR type dependent.
 587   This may be less than the product of the components of MAX_BLOCK_SIZE and is
 588   usually limited by the number of threads that can be resident simultaneously
 589   on a compute unit.
 590 * ``PIPE_COMPUTE_CAP_MAX_GLOBAL_SIZE``: Maximum size of the GLOBAL
 591   resource.  Value type: ``uint64_t``. Shader IR type dependent.
 592 * ``PIPE_COMPUTE_CAP_MAX_LOCAL_SIZE``: Maximum size of the LOCAL
 593   resource.  Value type: ``uint64_t``. Shader IR type dependent.
 594 * ``PIPE_COMPUTE_CAP_MAX_PRIVATE_SIZE``: Maximum size of the PRIVATE
 595   resource.  Value type: ``uint64_t``. Shader IR type dependent.
 596 * ``PIPE_COMPUTE_CAP_MAX_INPUT_SIZE``: Maximum size of the INPUT
 597   resource.  Value type: ``uint64_t``. Shader IR type dependent.
 598 * ``PIPE_COMPUTE_CAP_MAX_MEM_ALLOC_SIZE``: Maximum size of a memory object
 599   allocation in bytes.  Value type: ``uint64_t``.
 600 * ``PIPE_COMPUTE_CAP_MAX_CLOCK_FREQUENCY``: Maximum frequency of the GPU
 601   clock in MHz. Value type: ``uint32_t``
 602 * ``PIPE_COMPUTE_CAP_MAX_COMPUTE_UNITS``: Maximum number of compute units
 603   Value type: ``uint32_t``
 604 * ``PIPE_COMPUTE_CAP_IMAGES_SUPPORTED``: Whether images are supported
 605   non-zero means yes, zero means no. Value type: ``uint32_t``
 606 * ``PIPE_COMPUTE_CAP_SUBGROUP_SIZE``: The size of a basic execution unit in
 607   threads. Also known as wavefront size, warp size or SIMD width.
 608 * ``PIPE_COMPUTE_CAP_ADDRESS_BITS``: The default compute device address space
 609   size specified as an unsigned integer value in bits.
 610 * ``PIPE_COMPUTE_CAP_MAX_VARIABLE_THREADS_PER_BLOCK``: Maximum variable number
 611   of threads that a single block can contain. This is similar to
 612   PIPE_COMPUTE_CAP_MAX_THREADS_PER_BLOCK, except that the variable size is not
 613   known a compile-time but at dispatch-time.
 614
 615 .. _pipe_bind:
 616
 617 PIPE_BIND_*
 618 ^^^^^^^^^^^
 619
 620 These flags indicate how a resource will be used and are specified at resource
 621 creation time. Resources may be used in different roles
 622 during their lifecycle. Bind flags are cumulative and may be combined to create
 623 a resource which can be used for multiple things.
 624 Depending on the pipe driver's memory management and these bind flags,
 625 resources might be created and handled quite differently.
 626
 627 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
 628   rendered to.  Any surface/resource attached to pipe_framebuffer_state::cbufs
 629   must have this flag set.
 630 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
 631   depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
 632   have this flag set.
 633 * ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to
 634   query whether a device supports blending for a given format.
 635   If this flag is set, surface creation may fail if blending is not supported
 636   for the specified format. If it is not set, a driver may choose to ignore
 637   blending on surfaces with formats that would require emulation.
 638 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
 639   pipe_screen::flush_front_buffer must have this flag set.
 640 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
 641   or vertex shader.
 642 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
 643 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
 644 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
 645 * ``PIPE_BIND_STREAM_OUTPUT``: A stream output buffer.
 646 * ``PIPE_BIND_CUSTOM``:
 647 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
 648 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
 649   process.
 650 * ``PIPE_BIND_GLOBAL``: A buffer that can be mapped into the global
 651   address space of a compute program.
 652 * ``PIPE_BIND_SHADER_BUFFER``: A buffer without a format that can be bound
 653   to a shader and can be used with load, store, and atomic instructions.
 654 * ``PIPE_BIND_SHADER_IMAGE``: A buffer or texture with a format that can be
 655   bound to a shader and can be used with load, store, and atomic instructions.
 656 * ``PIPE_BIND_COMPUTE_RESOURCE``: A buffer or texture that can be
 657   bound to the compute program as a shader resource.
 658 * ``PIPE_BIND_COMMAND_ARGS_BUFFER``: A buffer that may be sourced by the
 659   GPU command processor. It can contain, for example, the arguments to
 660   indirect draw calls.
 661
 662 .. _pipe_usage:
 663
 664 PIPE_USAGE_*
 665 ^^^^^^^^^^^^
 666
 667 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
 668 Note that drivers must always support read and write CPU access at any time
 669 no matter which hint they got.
 670
 671 * ``PIPE_USAGE_DEFAULT``: Optimized for fast GPU access.
 672 * ``PIPE_USAGE_IMMUTABLE``: Optimized for fast GPU access and the resource is
 673   not expected to be mapped or changed (even by the GPU) after the first upload.
 674 * ``PIPE_USAGE_DYNAMIC``: Expect frequent write-only CPU access. What is
 675   uploaded is expected to be used at least several times by the GPU.
 676 * ``PIPE_USAGE_STREAM``: Expect frequent write-only CPU access. What is
 677   uploaded is expected to be used only once by the GPU.
 678 * ``PIPE_USAGE_STAGING``: Optimized for fast CPU access.
 679
 680
 681 Methods
 682 -------
 683
 684 XXX to-do
 685
 686 get_name
 687 ^^^^^^^^
 688
 689 Returns an identifying name for the screen.
 690
 691 The returned string should remain valid and immutable for the lifetime of
 692 pipe_screen.
 693
 694 get_vendor
 695 ^^^^^^^^^^
 696
 697 Returns the screen vendor.
 698
 699 The returned string should remain valid and immutable for the lifetime of
 700 pipe_screen.
 701
 702 get_device_vendor
 703 ^^^^^^^^^^^^^^^^^
 704
 705 Returns the actual vendor of the device driving the screen
 706 (as opposed to the driver vendor).
 707
 708 The returned string should remain valid and immutable for the lifetime of
 709 pipe_screen.
 710
 711 .. _get_param:
 712
 713 get_param
 714 ^^^^^^^^^
 715
 716 Get an integer/boolean screen parameter.
 717
 718 **param** is one of the :ref:`PIPE_CAP` names.
 719
 720 .. _get_paramf:
 721
 722 get_paramf
 723 ^^^^^^^^^^
 724
 725 Get a floating-point screen parameter.
 726
 727 **param** is one of the :ref:`PIPE_CAPF` names.
 728
 729 context_create
 730 ^^^^^^^^^^^^^^
 731
 732 Create a pipe_context.
 733
 734 **priv** is private data of the caller, which may be put to various
 735 unspecified uses, typically to do with implementing swapbuffers
 736 and/or front-buffer rendering.
 737
 738 is_format_supported
 739 ^^^^^^^^^^^^^^^^^^^
 740
 741 Determine if a resource in the given format can be used in a specific manner.
 742
 743 **format** the resource format
 744
 745 **target** one of the PIPE_TEXTURE_x flags
 746
 747 **sample_count** the number of samples. 0 and 1 mean no multisampling,
 748 the maximum allowed legal value is 32.
 749
 750 **storage_sample_count** the number of storage samples. This must be <=
 751 sample_count. See the documentation of ``pipe_resource::nr_storage_samples``.
 752
 753 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
 754
 755 Returns TRUE if all usages can be satisfied.
 756
 757
 758 can_create_resource
 759 ^^^^^^^^^^^^^^^^^^^
 760
 761 Check if a resource can actually be created (but don't actually allocate any
 762 memory).  This is used to implement OpenGL's proxy textures.  Typically, a
 763 driver will simply check if the total size of the given resource is less than
 764 some limit.
 765
 766 For PIPE_TEXTURE_CUBE, the pipe_resource::array_size field should be 6.
 767
 768
 769 .. _resource_create:
 770
 771 resource_create
 772 ^^^^^^^^^^^^^^^
 773
 774 Create a new resource from a template.
 775 The following fields of the pipe_resource must be specified in the template:
 776
 777 **target** one of the pipe_texture_target enums.
 778 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
 779 Modern APIs allow using buffers as shader resources.
 780
 781 **format** one of the pipe_format enums.
 782
 783 **width0** the width of the base mip level of the texture or size of the buffer.
 784
 785 **height0** the height of the base mip level of the texture
 786 (1 for 1D or 1D array textures).
 787
 788 **depth0** the depth of the base mip level of the texture
 789 (1 for everything else).
 790
 791 **array_size** the array size for 1D and 2D array textures.
 792 For cube maps this must be 6, for other textures 1.
 793
 794 **last_level** the last mip map level present.
 795
 796 **nr_samples**: Number of samples determining quality, driving the rasterizer,
 797 shading, and framebuffer. It is the number of samples seen by the whole
 798 graphics pipeline. 0 and 1 specify a resource which isn't multisampled.
 799
 800 **nr_storage_samples**: Only color buffers can set this lower than nr_samples.
 801 Multiple samples within a pixel can have the same color. ``nr_storage_samples``
 802 determines how many slots for different colors there are per pixel.
 803 If there are not enough slots to store all sample colors, some samples will
 804 have an undefined color (called "undefined samples").
 805
 806 The resolve blit behavior is driver-specific, but can be one of these two:
 807 1. Only defined samples will be averaged. Undefined samples will be ignored.
 808 2. Undefined samples will be approximated by looking at surrounding defined
 809    samples (even in different pixels).
 810
 811 Blits and MSAA texturing: If the sample being fetched is undefined, one of
 812 the defined samples is returned instead.
 813
 814 Sample shading (``set_min_samples``) will operate at a sample frequency that
 815 is at most ``nr_storage_samples``. Greater ``min_samples`` values will be
 816 replaced by ``nr_storage_samples``.
 817
 818 **usage** one of the :ref:`PIPE_USAGE` flags.
 819
 820 **bind** bitmask of the :ref:`PIPE_BIND` flags.
 821
 822 **flags** bitmask of PIPE_RESOURCE_FLAG flags.
 823
 824
 825
 826 resource_changed
 827 ^^^^^^^^^^^^^^^^
 828
 829 Mark a resource as changed so derived internal resources will be recreated
 830 on next use.
 831
 832 When importing external images that can't be directly used as texture sampler
 833 source, internal copies may have to be created that the hardware can sample
 834 from. When those resources are reimported, the image data may have changed, and
 835 the previously derived internal resources must be invalidated to avoid sampling
 836 from old copies.
 837
 838
 839
 840 resource_destroy
 841 ^^^^^^^^^^^^^^^^
 842
 843 Destroy a resource. A resource is destroyed if it has no more references.
 844
 845
 846
 847 get_timestamp
 848 ^^^^^^^^^^^^^
 849
 850 Query a timestamp in nanoseconds. The returned value should match
 851 PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't
 852 wait for rendering to complete (which cannot be achieved with queries).
 853
 854
 855
 856 get_driver_query_info
 857 ^^^^^^^^^^^^^^^^^^^^^
 858
 859 Return a driver-specific query. If the **info** parameter is NULL,
 860 the number of available queries is returned.  Otherwise, the driver
 861 query at the specified **index** is returned in **info**.
 862 The function returns non-zero on success.
 863 The driver-specific query is described with the pipe_driver_query_info
 864 structure.
 865
 866 get_driver_query_group_info
 867 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 868
 869 Return a driver-specific query group. If the **info** parameter is NULL,
 870 the number of available groups is returned.  Otherwise, the driver
 871 query group at the specified **index** is returned in **info**.
 872 The function returns non-zero on success.
 873 The driver-specific query group is described with the
 874 pipe_driver_query_group_info structure.
 875
 876
 877
 878 get_disk_shader_cache
 879 ^^^^^^^^^^^^^^^^^^^^^
 880
 881 Returns a pointer to a driver-specific on-disk shader cache. If the driver
 882 failed to create the cache or does not support an on-disk shader cache NULL is
 883 returned. The callback itself may also be NULL if the driver doesn't support
 884 an on-disk shader cache.
 885
 886
 887 Thread safety
 888 -------------
 889
 890 Screen methods are required to be thread safe. While gallium rendering
 891 contexts are not required to be thread safe, it is required to be safe to use
 892 different contexts created with the same screen in different threads without
 893 locks. It is also required to be safe using screen methods in a thread, while
 894 using one of its contexts in another (without locks).