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