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 * ``MAX_TEXTURE_IMAGE_UNITS``: The maximum number of samplers available.
  26 * ``NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
  27   normalized coordinates, and mipmaps.
  28 * ``TWO_SIDED_STENCIL``: Whether the stencil test can also affect back-facing
  29   polygons.
  30 * ``GLSL``: Deprecated.
  31 * ``DUAL_SOURCE_BLEND``: Whether dual-source blend factors are supported. See
  32   :ref:`Blend` for more information.
  33 * ``ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
  34 * ``POINT_SPRITE``: Whether point sprites are available.
  35 * ``MAX_RENDER_TARGETS``: The maximum number of render targets that may be
  36   bound.
  37 * ``OCCLUSION_QUERY``: Whether occlusion queries are available.
  38 * ``TIMER_QUERY``: Whether timer queries are available.
  39 * ``TEXTURE_SHADOW_MAP``: XXX
  40 * ``MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
  41   for a 2D texture.
  42 * ``MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
  43   for a 3D texture.
  44 * ``MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
  45   for a cubemap.
  46 * ``TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
  47   are supported.
  48 * ``TEXTURE_MIRROR_REPEAT``: Whether mirrored repeating texture coordinates
  49   are supported.
  50 * ``MAX_VERTEX_TEXTURE_UNITS``: The maximum number of samplers addressable
  51   inside the vertex shader. If this is 0, then the vertex shader cannot
  52   sample textures.
  53 * ``TGSI_CONT_SUPPORTED``: Whether the TGSI CONT opcode is supported.
  54 * ``BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
  55   from color blend equations, in :ref:`Blend` state.
  56 * ``SM3``: Whether the vertex shader and fragment shader support equivalent
  57   opcodes to the Shader Model 3 specification. XXX oh god this is horrible
  58 * ``MAX_PREDICATE_REGISTERS``: XXX
  59 * ``MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
  60   the vertex and fragment shader, inclusive.
  61 * ``MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
  62   to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
  63   only permit binding one constant buffer per shader, and the shaders will
  64   not permit two-dimensional access to constants.
  65
  66 If a value greater than 0 is returned, the driver can have multiple
  67 constant buffers bound to shader stages. The CONST register file can
  68 be accessed with two-dimensional indices, like in the example below.
  69
  70 DCL CONST[0][0..7]       # declare first 8 vectors of constbuf 0
  71 DCL CONST[3][0]          # declare first vector of constbuf 3
  72 MOV OUT[0], CONST[0][3]  # copy vector 3 of constbuf 0
  73
  74 For backwards compatibility, one-dimensional access to CONST register
  75 file is still supported. In that case, the constbuf index is assumed
  76 to be 0.
  77
  78 * ``MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant buffer.
  79 * ``INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
  80   masks are supported. If 0, then the first rendertarget's blend mask is
  81   replicated across all MRTs.
  82 * ``INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
  83   available. If 0, then the first rendertarget's blend functions affect all
  84   MRTs.
  85 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
  86   FS_COORD_ORIGIN with value UPPER_LEFT is supported.
  87 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
  88   FS_COORD_ORIGIN with value LOWER_LEFT is supported.
  89 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
  90   property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
  91 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
  92   property FS_COORD_PIXEL_CENTER with value INTEGER is supported.
  93
  94 The floating-point capabilities:
  95
  96 * ``MAX_LINE_WIDTH``: The maximum width of a regular line.
  97 * ``MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
  98 * ``MAX_POINT_WIDTH``: The maximum width and height of a point.
  99 * ``MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
 100 * ``MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
 101   applied to anisotropically filtered textures.
 102 * ``MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
 103   to filtered textures.
 104 * ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``,
 105   ``GUARD_BAND_BOTTOM``: XXX
 106
 107 Fragment shader limits:
 108
 109 * ``PIPE_CAP_MAX_FS_INSTRUCTIONS``: The maximum number of instructions.
 110 * ``PIPE_CAP_MAX_FS_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
 111 * ``PIPE_CAP_MAX_FS_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
 112 * ``PIPE_CAP_MAX_FS_TEX_INDIRECTIONS``: The maximum number of texture indirections.
 113 * ``PIPE_CAP_MAX_FS_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
 114 * ``PIPE_CAP_MAX_FS_INPUTS``: The maximum number of input registers.
 115 * ``PIPE_CAP_MAX_FS_CONSTS``: The maximum number of constants.
 116 * ``PIPE_CAP_MAX_FS_TEMPS``: The maximum number of temporary registers.
 117 * ``PIPE_CAP_MAX_FS_ADDRS``: The maximum number of address registers.
 118 * ``PIPE_CAP_MAX_FS_PREDS``: The maximum number of predicate registers.
 119
 120 Vertex shader limits:
 121
 122 * ``PIPE_CAP_MAX_VS_*``: Identical to ``PIPE_CAP_MAX_FS_*``.
 123
 124
 125 .. _pipe_bind:
 126
 127 PIPE_BIND_*
 128 ^^^^^^^^^^^
 129
 130 These flags indicate how a resource will be used and are specified at resource
 131 creation time. Resources may be used in different roles
 132 during their lifecycle. Bind flags are cumulative and may be combined to create
 133 a resource which can be used for multiple things.
 134 Depending on the pipe driver's memory management and these bind flags,
 135 resources might be created and handled quite differently.
 136
 137 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
 138   rendered to.  Any surface/resource attached to pipe_framebuffer_state::cbufs
 139   must have this flag set.
 140 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
 141   depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
 142   have this flag set.
 143 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
 144   pipe_screen::flush_front_buffer must have this flag set.
 145 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
 146   or vertex shader.
 147 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
 148 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
 149 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
 150 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to.
 151 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from.
 152 * ``PIPE_BIND_CUSTOM``:
 153 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
 154 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
 155   process.
 156
 157 .. _pipe_usage:
 158
 159 PIPE_USAGE_*
 160 ^^^^^^^^^^^^
 161
 162 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
 163
 164 * ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws.
 165 * ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
 166 * ``PIPE_USAGE_STATIC``: Same as immutable (?)
 167 * ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload.
 168 * ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ...
 169
 170
 171
 172 PIPE_TEXTURE_GEOM
 173 ^^^^^^^^^^^^^^^^^
 174
 175 These flags are used when querying whether a particular pipe_format is
 176 supported by the driver (with the `is_format_supported` function).
 177 Some formats may only be supported for certain kinds of textures.
 178 For example, a compressed format might only be used for POT textures.
 179
 180 * ``PIPE_TEXTURE_GEOM_NON_SQUARE``: The texture may not be square
 181 * ``PIPE_TEXTURE_GEOM_NON_POWER_OF_TWO``: The texture dimensions may not be
 182   powers of two.
 183
 184
 185 Methods
 186 -------
 187
 188 XXX to-do
 189
 190 get_name
 191 ^^^^^^^^
 192
 193 Returns an identifying name for the screen.
 194
 195 get_vendor
 196 ^^^^^^^^^^
 197
 198 Returns the screen vendor.
 199
 200 .. _get_param:
 201
 202 get_param
 203 ^^^^^^^^^
 204
 205 Get an integer/boolean screen parameter.
 206
 207 **param** is one of the :ref:`PIPE_CAP` names.
 208
 209 .. _get_paramf:
 210
 211 get_paramf
 212 ^^^^^^^^^^
 213
 214 Get a floating-point screen parameter.
 215
 216 **param** is one of the :ref:`PIPE_CAP` names.
 217
 218 context_create
 219 ^^^^^^^^^^^^^^
 220
 221 Create a pipe_context.
 222
 223 **priv** is private data of the caller, which may be put to various
 224 unspecified uses, typically to do with implementing swapbuffers
 225 and/or front-buffer rendering.
 226
 227 is_format_supported
 228 ^^^^^^^^^^^^^^^^^^^
 229
 230 Determine if a resource in the given format can be used in a specific manner.
 231
 232 **format** the resource format
 233
 234 **target** one of the PIPE_TEXTURE_x flags
 235
 236 **sample_count** the number of samples. 0 and 1 mean no multisampling,
 237 the maximum allowed legal value is 32.
 238
 239 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
 240
 241 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags.
 242
 243 Returns TRUE if all usages can be satisfied.
 244
 245 .. _resource_create:
 246
 247 resource_create
 248 ^^^^^^^^^^^^^^^
 249
 250 Create a new resource from a template.
 251 The following fields of the pipe_resource must be specified in the template:
 252
 253 target
 254
 255 format
 256
 257 width0
 258
 259 height0
 260
 261 depth0
 262
 263 last_level
 264
 265 nr_samples
 266
 267 usage
 268
 269 bind
 270
 271 flags
 272
 273
 274
 275 resource_destroy
 276 ^^^^^^^^^^^^^^^^
 277
 278 Destroy a resource. A resource is destroyed if it has no more references.
 279