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_bind:
 107
 108 PIPE_BIND
 109 ^^^^^^^^^
 110
 111 These flags control resource creation. Resources may be used in different roles
 112 during their lifecycle. Bind flags are cumulative and may be combined to create
 113 a resource which can be used as multiple things.
 114 Depending on the pipe driver's memory management, depending on these bind flags
 115 resources might be created and handled quite differently.
 116
 117 * ``RENDER_TARGET``: A color buffer or pixel buffer which will be rendered to.
 118 * ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
 119 * ``DEPTH_STENCIL``: A depth (Z) buffer or stencil buffer.  Gallium does
 120   not explicitly provide for stencil-only buffers, so any stencil buffer
 121   validated here is implicitly also a depth buffer.
 122 * ``SAMPLER_VIEW``: A texture that may be sampled from in a fragment or vertex
 123   shader.
 124 * ``VERTEX_BUFFER``: A vertex buffer.
 125 * ``INDEX_BUFFER``: An element buffer.
 126 * ``CONSTANT_BUFFER``: A buffer of shader constants.
 127 * ``BLIT_SOURCE``: A blit source, as given to surface_copy.
 128 * ``BLIT_DESTINATION``: A blit destination, as given to surface_copy and surface_fill.
 129 * ``TRANSFER_WRITE``: A transfer object which will be written to.
 130 * ``TRANSFER_READ``: A transfer object which will be read from.
 131 * ``CUSTOM``:
 132 * ``SCANOUT``: A front color buffer or scanout buffer.
 133 * ``SHARED``:
 134
 135 .. _pipe_usage:
 136
 137 PIPE_USAGE
 138 ^^^^^^^^^^
 139
 140 The PIPE_USAGE enums are hints about the expected lifecycle of a resource.
 141 * ``DEFAULT``: Expect many uploads to the resource, intermixed with draws.
 142 * ``DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
 143 * ``STATIC``: Same as immutable (?)
 144 * ``IMMUTABLE``: Resource will not be changed after first upload.
 145 * ``STREAM``: Upload will be followed by draw, followed by upload, ...
 146
 147
 148
 149 PIPE_TEXTURE_GEOM
 150 ^^^^^^^^^^^^^^^^^
 151
 152 These flags are used when querying whether a particular pipe_format is
 153 supported by the driver (with the `is_format_supported` function).
 154 Some formats may only be supported for certain kinds of textures.
 155 For example, a compressed format might only be used for POT textures.
 156
 157 * ``PIPE_TEXTURE_GEOM_NON_SQUARE``: The texture may not be square
 158 * ``PIPE_TEXTURE_GEOM_NON_POWER_OF_TWO``: The texture dimensions may not be
 159   powers of two.
 160
 161
 162 Methods
 163 -------
 164
 165 XXX moar; got bored
 166
 167 get_name
 168 ^^^^^^^^
 169
 170 Returns an identifying name for the screen.
 171
 172 get_vendor
 173 ^^^^^^^^^^
 174
 175 Returns the screen vendor.
 176
 177 .. _get_param:
 178
 179 get_param
 180 ^^^^^^^^^
 181
 182 Get an integer/boolean screen parameter.
 183
 184 **param** is one of the :ref:`PIPE_CAP` names.
 185
 186 .. _get_paramf:
 187
 188 get_paramf
 189 ^^^^^^^^^^
 190
 191 Get a floating-point screen parameter.
 192
 193 **param** is one of the :ref:`PIPE_CAP` names.
 194
 195 context_create
 196 ^^^^^^^^^^^^^^
 197
 198 Create a pipe_context.
 199
 200 **priv** is private data of the caller, which may be put to various
 201 unspecified uses, typically to do with implementing swapbuffers
 202 and/or front-buffer rendering.
 203
 204 is_format_supported
 205 ^^^^^^^^^^^^^^^^^^^
 206
 207 See if a format can be used in a specific manner.
 208
 209 **tex_usage** is a bitmask of :ref:`PIPE_BIND` flags.
 210
 211 Returns TRUE if all usages can be satisfied.
 212
 213
 214 .. _resource_create:
 215
 216 resource_create
 217 ^^^^^^^^^^^^^^
 218
 219 Given a template of texture setup, create a resource.
 220 The way a resource may be used is specifed by bind flags, :ref:`pipe_bind`.
 221 and hints are used to indicate to the driver what access pattern might be
 222 likely, :ref:`pipe_usage`.
 223
 224 resource_destroy
 225 ^^^^^^^^^^^^^^^
 226
 227 Destroy a resource. A resource is destroyed if it has no more references.
 228