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