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
  61 The floating-point capabilities:
  62
  63 * ``MAX_LINE_WIDTH``: The maximum width of a regular line.
  64 * ``MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
  65 * ``MAX_POINT_WIDTH``: The maximum width and height of a point.
  66 * ``MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
  67 * ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``,
  68   ``GUARD_BAND_BOTTOM``: XXX
  69
  70 XXX Is there a better home for this? vvv
  71
  72 If 0 is returned, the driver is not aware of multiple constant buffers,
  73 supports binding of only one constant buffer, and does not support
  74 two-dimensional CONST register file access in TGSI shaders.
  75
  76 If a value greater than 0 is returned, the driver can have multiple
  77 constant buffers bound to shader stages. The CONST register file can
  78 be accessed with two-dimensional indices, like in the example below.
  79
  80 DCL CONST[0][0..7]       # declare first 8 vectors of constbuf 0
  81 DCL CONST[3][0]          # declare first vector of constbuf 3
  82 MOV OUT[0], CONST[0][3]  # copy vector 3 of constbuf 0
  83
  84 For backwards compatibility, one-dimensional access to CONST register
  85 file is still supported. In that case, the constbuf index is assumed
  86 to be 0.
  87
  88 .. _pipe_buffer_usage:
  89
  90 PIPE_BUFFER_USAGE
  91 ^^^^^^^^^^^^^^^^^
  92
  93 These flags control buffer creation. Buffers may only have one role, so
  94 care should be taken to not allocate a buffer with the wrong usage.
  95
  96 * ``PIXEL``: This is the flag to use for all textures.
  97 * ``VERTEX``: A vertex buffer.
  98 * ``INDEX``: An element buffer.
  99 * ``CONSTANT``: A buffer of shader constants.
 100
 101 Buffers are inevitably abstracting the pipe's underlying memory management,
 102 so many of their usage flags can be used to direct the way the buffer is
 103 handled.
 104
 105 * ``CPU_READ``, ``CPU_WRITE``: Whether the user will map and, in the case of
 106   the latter, write to, the buffer. The convenience flag ``CPU_READ_WRITE`` is
 107   available to signify a read/write buffer.
 108 * ``GPU_READ``, ``GPU_WRITE``: Whether the driver will internally need to
 109   read from or write to the buffer. The latter will only happen if the buffer
 110   is made into a render target.
 111 * ``DISCARD``: When set on a map, the contents of the map will be discarded
 112   beforehand. Cannot be used with ``CPU_READ``.
 113 * ``DONTBLOCK``: When set on a map, the map will fail if the buffer cannot be
 114   mapped immediately.
 115 * ``UNSYNCHRONIZED``: When set on a map, any outstanding operations on the
 116   buffer will be ignored. The interaction of any writes to the map and any
 117   operations pending with the buffer are undefined. Cannot be used with
 118   ``CPU_READ``.
 119 * ``FLUSH_EXPLICIT``: When set on a map, written ranges of the map require
 120   explicit flushes using :ref:`buffer_flush_mapped_range`. Requires
 121   ``CPU_WRITE``.
 122
 123 .. _pipe_texture_usage:
 124
 125 PIPE_TEXTURE_USAGE
 126 ^^^^^^^^^^^^^^^^^^
 127
 128 These flags determine the possible roles a texture may be used for during its
 129 lifetime. Texture usage flags are cumulative and may be combined to create a
 130 texture that can be used as multiple things.
 131
 132 * ``RENDER_TARGET``: A colorbuffer or pixelbuffer.
 133 * ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
 134 * ``PRIMARY``: A frontbuffer or scanout buffer.
 135 * ``DEPTH_STENCIL``: A depthbuffer, stencilbuffer, or Z buffer. Gallium does
 136   not explicitly provide for stencil-only buffers, so any stencilbuffer
 137   validated here is implicitly also a depthbuffer.
 138 * ``SAMPLER``: A texture that may be sampled from in a fragment or vertex
 139   shader.
 140 * ``DYNAMIC``: A texture that will be mapped frequently.
 141
 142 Methods
 143 -------
 144
 145 XXX moar; got bored
 146
 147 get_name
 148 ^^^^^^^^
 149
 150 Returns an identifying name for the screen.
 151
 152 get_vendor
 153 ^^^^^^^^^^
 154
 155 Returns the screen vendor.
 156
 157 .. _get_param:
 158
 159 get_param
 160 ^^^^^^^^^
 161
 162 Get an integer/boolean screen parameter.
 163
 164 **param** is one of the :ref:`PIPE_CAP` names.
 165
 166 .. _get_paramf:
 167
 168 get_paramf
 169 ^^^^^^^^^^
 170
 171 Get a floating-point screen parameter.
 172
 173 **param** is one of the :ref:`PIPE_CAP` names.
 174
 175 is_format_supported
 176 ^^^^^^^^^^^^^^^^^^^
 177
 178 See if a format can be used in a specific manner.
 179
 180 **usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
 181
 182 Returns TRUE if all usages can be satisfied.
 183
 184 .. note::
 185
 186    ``PIPE_TEXTURE_USAGE_DYNAMIC`` is not a valid usage.
 187
 188 .. _texture_create:
 189
 190 texture_create
 191 ^^^^^^^^^^^^^^
 192
 193 Given a template of texture setup, create a buffer and texture.
 194
 195 texture_blanket
 196 ^^^^^^^^^^^^^^^
 197
 198 Like :ref:`texture_create`, but use a supplied buffer instead of creating a
 199 new one.
 200
 201 texture_destroy
 202 ^^^^^^^^^^^^^^^
 203
 204 Destroy a texture. The buffer backing the texture is destroyed if it has no
 205 more references.
 206
 207 buffer_map
 208 ^^^^^^^^^^
 209
 210 Map a buffer into memory.
 211
 212 **usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
 213
 214 Returns a pointer to the map, or NULL if the mapping failed.
 215
 216 buffer_map_range
 217 ^^^^^^^^^^^^^^^^
 218
 219 Map a range of a buffer into memory.
 220
 221 The returned map is always relative to the beginning of the buffer, not the
 222 beginning of the mapped range.
 223
 224 .. _buffer_flush_mapped_range:
 225
 226 buffer_flush_mapped_range
 227 ^^^^^^^^^^^^^^^^^^^^^^^^^
 228
 229 Flush a range of mapped memory into a buffer.
 230
 231 The buffer must have been mapped with ``PIPE_BUFFER_USAGE_FLUSH_EXPLICIT``.
 232
 233 **usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
 234
 235 buffer_unmap
 236 ^^^^^^^^^^^^
 237
 238 Unmap a buffer from memory.
 239
 240 Any pointers into the map should be considered invalid and discarded.