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