src/gallium/docs/source/screen.rst

   1 Screen
   2 ======
   3
   4 A screen is an object representing the context-independent part of a device.
   5
   6 Useful Flags
   7 ------------
   8
   9 .. _pipe_cap:
  10
  11 PIPE_CAP
  12 ^^^^^^^^
  13
  14 Pipe capabilities help expose hardware functionality not explicitly required
  15 by Gallium. For floating-point values, use :ref:`get_paramf`, and for boolean
  16 or integer values, use :ref:`get_param`.
  17
  18 The integer capabilities:
  19
  20 * ``MAX_TEXTURE_IMAGE_UNITS``: The maximum number of samplers available.
  21 * ``NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
  22   normalized coordinates, and mipmaps.
  23 * ``TWO_SIDED_STENCIL``: Whether the stencil test can also affect back-facing
  24   polygons.
  25 * ``GLSL``: Deprecated.
  26 * ``DUAL_SOURCE_BLEND``: Whether dual-source blend factors are supported. See
  27   :ref:`Blend` for more information.
  28 * ``ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
  29 * ``POINT_SPRITE``: Whether point sprites are available.
  30 * ``MAX_RENDER_TARGETS``: The maximum number of render targets that may be
  31   bound.
  32 * ``OCCLUSION_QUERY``: Whether occlusion queries are available.
  33 * ``TEXTURE_SHADOW_MAP``: XXX
  34 * ``MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
  35   for a 2D texture.
  36 * ``MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
  37   for a 3D texture.
  38 * ``MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
  39   for a cubemap.
  40 * ``TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
  41   are supported.
  42 * ``TEXTURE_MIRROR_REPEAT``: Whether mirrored repeating texture coordinates
  43   are supported.
  44 * ``MAX_VERTEX_TEXTURE_UNITS``: The maximum number of samplers addressable
  45   inside the vertex shader. If this is 0, then the vertex shader cannot
  46   sample textures.
  47 * ``TGSI_CONT_SUPPORTED``: Whether the TGSI CONT opcode is supported.
  48 * ``BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
  49   from color blend equations, in :ref:`Blend` state.
  50 * ``SM3``: Whether the vertex shader and fragment shader support equivalent
  51   opcodes to the Shader Model 3 specification. XXX oh god this is horrible
  52 * ``MAX_PREDICATE_REGISTERS``: XXX
  53 * ``MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
  54   the vertex and fragment shader, inclusive.
  55 * ``MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
  56   to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
  57   only permit binding one constant buffer per shader, and the shaders will
  58   not permit two-dimensional access to constants.
  59 * ``MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant buffer.
  60 * ``INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
  61   masks are supported. If 0, then the first rendertarget's blend mask is
  62   replicated across all MRTs.
  63 * ``INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
  64   available. If 0, then the first rendertarget's blend functions affect all
  65   MRTs.
  66 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
  67   FS_COORD_ORIGIN with value UPPER_LEFT is supported.
  68 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
  69   FS_COORD_ORIGIN with value LOWER_LEFT is supported.
  70 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
  71   property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
  72 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
  73   property FS_COORD_PIXEL_CENTER with value INTEGER is supported.
  74
  75 The floating-point capabilities:
  76
  77 * ``MAX_LINE_WIDTH``: The maximum width of a regular line.
  78 * ``MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
  79 * ``MAX_POINT_WIDTH``: The maximum width and height of a point.
  80 * ``MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
  81 * ``MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
  82   applied to anisotropically filtered textures.
  83 * ``MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
  84   to filtered textures.
  85 * ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``,
  86   ``GUARD_BAND_BOTTOM``: XXX
  87
  88 XXX Is there a better home for this? vvv
  89
  90 If 0 is returned, the driver is not aware of multiple constant buffers,
  91 supports binding of only one constant buffer, and does not support
  92 two-dimensional CONST register file access in TGSI shaders.
  93
  94 If a value greater than 0 is returned, the driver can have multiple
  95 constant buffers bound to shader stages. The CONST register file can
  96 be accessed with two-dimensional indices, like in the example below.
  97
  98 DCL CONST[0][0..7]       # declare first 8 vectors of constbuf 0
  99 DCL CONST[3][0]          # declare first vector of constbuf 3
 100 MOV OUT[0], CONST[0][3]  # copy vector 3 of constbuf 0
 101
 102 For backwards compatibility, one-dimensional access to CONST register
 103 file is still supported. In that case, the constbuf index is assumed
 104 to be 0.
 105
 106 .. _pipe_buffer_usage:
 107
 108 PIPE_BUFFER_USAGE
 109 ^^^^^^^^^^^^^^^^^
 110
 111 These flags control buffer creation. Buffers may only have one role, so
 112 care should be taken to not allocate a buffer with the wrong usage.
 113
 114 * ``PIXEL``: This is the flag to use for all textures.
 115 * ``VERTEX``: A vertex buffer.
 116 * ``INDEX``: An element buffer.
 117 * ``CONSTANT``: A buffer of shader constants.
 118
 119 Buffers are inevitably abstracting the pipe's underlying memory management,
 120 so many of their usage flags can be used to direct the way the buffer is
 121 handled.
 122
 123 * ``CPU_READ``, ``CPU_WRITE``: Whether the user will map and, in the case of
 124   the latter, write to, the buffer. The convenience flag ``CPU_READ_WRITE`` is
 125   available to signify a read/write buffer.
 126 * ``GPU_READ``, ``GPU_WRITE``: Whether the driver will internally need to
 127   read from or write to the buffer. The latter will only happen if the buffer
 128   is made into a render target.
 129 * ``DISCARD``: When set on a map, the contents of the map will be discarded
 130   beforehand. Cannot be used with ``CPU_READ``.
 131 * ``DONTBLOCK``: When set on a map, the map will fail if the buffer cannot be
 132   mapped immediately.
 133 * ``UNSYNCHRONIZED``: When set on a map, any outstanding operations on the
 134   buffer will be ignored. The interaction of any writes to the map and any
 135   operations pending with the buffer are undefined. Cannot be used with
 136   ``CPU_READ``.
 137 * ``FLUSH_EXPLICIT``: When set on a map, written ranges of the map require
 138   explicit flushes using :ref:`buffer_flush_mapped_range`. Requires
 139   ``CPU_WRITE``.
 140
 141 .. _pipe_texture_usage:
 142
 143 PIPE_TEXTURE_USAGE
 144 ^^^^^^^^^^^^^^^^^^
 145
 146 These flags determine the possible roles a texture may be used for during its
 147 lifetime. Texture usage flags are cumulative and may be combined to create a
 148 texture that can be used as multiple things.
 149
 150 * ``RENDER_TARGET``: A color buffer or pixel buffer which will be rendered to.
 151 * ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
 152 * ``PRIMARY``: A front color buffer or scanout buffer.
 153 * ``DEPTH_STENCIL``: A depth (Z) buffer or stencil buffer.  Gallium does
 154   not explicitly provide for stencil-only buffers, so any stencil buffer
 155   validated here is implicitly also a depth buffer.
 156 * ``SAMPLER``: A texture that may be sampled from in a fragment or vertex
 157   shader.
 158 * ``DYNAMIC``: A texture that will be mapped frequently.
 159
 160
 161 PIPE_TEXTURE_GEOM
 162 ^^^^^^^^^^^^^^^^^
 163
 164 These flags are used when querying whether a particular pipe_format is
 165 supported by the driver (with the `is_format_supported` function).
 166 Some formats may only be supported for certain kinds of textures.
 167 For example, a compressed format might only be used for POT textures.
 168
 169 * ``PIPE_TEXTURE_GEOM_NON_SQUARE``: The texture may not be square
 170 * ``PIPE_TEXTURE_GEOM_NON_POWER_OF_TWO``: The texture dimensions may not be
 171   powers of two.
 172
 173
 174 Methods
 175 -------
 176
 177 XXX moar; got bored
 178
 179 get_name
 180 ^^^^^^^^
 181
 182 Returns an identifying name for the screen.
 183
 184 get_vendor
 185 ^^^^^^^^^^
 186
 187 Returns the screen vendor.
 188
 189 .. _get_param:
 190
 191 get_param
 192 ^^^^^^^^^
 193
 194 Get an integer/boolean screen parameter.
 195
 196 **param** is one of the :ref:`PIPE_CAP` names.
 197
 198 .. _get_paramf:
 199
 200 get_paramf
 201 ^^^^^^^^^^
 202
 203 Get a floating-point screen parameter.
 204
 205 **param** is one of the :ref:`PIPE_CAP` names.
 206
 207 context_create
 208 ^^^^^^^^^^^^^^
 209
 210 Create a pipe_context.
 211
 212 **priv** is private data of the caller, which may be put to various
 213 unspecified uses, typically to do with implementing swapbuffers
 214 and/or front-buffer rendering.
 215
 216 is_format_supported
 217 ^^^^^^^^^^^^^^^^^^^
 218
 219 See if a format can be used in a specific manner.
 220
 221 **usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
 222
 223 Returns TRUE if all usages can be satisfied.
 224
 225 .. note::
 226
 227    ``PIPE_TEXTURE_USAGE_DYNAMIC`` is not a valid usage.
 228
 229 .. _texture_create:
 230
 231 texture_create
 232 ^^^^^^^^^^^^^^
 233
 234 Given a template of texture setup, create a buffer and texture.
 235
 236 texture_blanket
 237 ^^^^^^^^^^^^^^^
 238
 239 Like :ref:`texture_create`, but use a supplied buffer instead of creating a
 240 new one.
 241
 242 texture_destroy
 243 ^^^^^^^^^^^^^^^
 244
 245 Destroy a texture. The buffer backing the texture is destroyed if it has no
 246 more references.
 247
 248 buffer_map
 249 ^^^^^^^^^^
 250
 251 Map a buffer into memory.
 252
 253 **usage** is a bitmask of :ref:`PIPE_BUFFER_USAGE` flags.
 254
 255 Returns a pointer to the map, or NULL if the mapping failed.
 256
 257 buffer_map_range
 258 ^^^^^^^^^^^^^^^^
 259
 260 Map a range of a buffer into memory.
 261
 262 The returned map is always relative to the beginning of the buffer, not the
 263 beginning of the mapped range.
 264
 265 .. _buffer_flush_mapped_range:
 266
 267 buffer_flush_mapped_range
 268 ^^^^^^^^^^^^^^^^^^^^^^^^^
 269
 270 Flush a range of mapped memory into a buffer.
 271
 272 The buffer must have been mapped with ``PIPE_BUFFER_USAGE_FLUSH_EXPLICIT``.
 273
 274 **usage** is a bitmask of :ref:`PIPE_BUFFER_USAGE` flags.
 275
 276 buffer_unmap
 277 ^^^^^^^^^^^^
 278
 279 Unmap a buffer from memory.
 280
 281 Any pointers into the map should be considered invalid and discarded.