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