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_BLIT_SOURCE``: A blit source, as given to surface_copy.
 132 * ``PIPE_BIND_BLIT_DESTINATION``: A blit destination, as given to surface_copy
 133   and surface_fill.
 134 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to.
 135 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from.
 136 * ``PIPE_BIND_CUSTOM``:
 137 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
 138 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
 139   process.
 140
 141 .. _pipe_usage:
 142
 143 PIPE_USAGE_*
 144 ^^^^^^^^^^^^
 145
 146 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
 147
 148 * ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws.
 149 * ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
 150 * ``PIPE_USAGE_STATIC``: Same as immutable (?)
 151 * ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload.
 152 * ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ...
 153
 154
 155
 156 PIPE_TEXTURE_GEOM
 157 ^^^^^^^^^^^^^^^^^
 158
 159 These flags are used when querying whether a particular pipe_format is
 160 supported by the driver (with the `is_format_supported` function).
 161 Some formats may only be supported for certain kinds of textures.
 162 For example, a compressed format might only be used for POT textures.
 163
 164 * ``PIPE_TEXTURE_GEOM_NON_SQUARE``: The texture may not be square
 165 * ``PIPE_TEXTURE_GEOM_NON_POWER_OF_TWO``: The texture dimensions may not be
 166   powers of two.
 167
 168
 169 Methods
 170 -------
 171
 172 XXX to-do
 173
 174 get_name
 175 ^^^^^^^^
 176
 177 Returns an identifying name for the screen.
 178
 179 get_vendor
 180 ^^^^^^^^^^
 181
 182 Returns the screen vendor.
 183
 184 .. _get_param:
 185
 186 get_param
 187 ^^^^^^^^^
 188
 189 Get an integer/boolean screen parameter.
 190
 191 **param** is one of the :ref:`PIPE_CAP` names.
 192
 193 .. _get_paramf:
 194
 195 get_paramf
 196 ^^^^^^^^^^
 197
 198 Get a floating-point screen parameter.
 199
 200 **param** is one of the :ref:`PIPE_CAP` names.
 201
 202 context_create
 203 ^^^^^^^^^^^^^^
 204
 205 Create a pipe_context.
 206
 207 **priv** is private data of the caller, which may be put to various
 208 unspecified uses, typically to do with implementing swapbuffers
 209 and/or front-buffer rendering.
 210
 211 is_format_supported
 212 ^^^^^^^^^^^^^^^^^^^
 213
 214 Determine if a resource in the given format can be used in a specific manner.
 215
 216 **format** the resource format
 217
 218 **target** one of the PIPE_TEXTURE_x flags
 219
 220 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
 221
 222 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags.
 223
 224 Returns TRUE if all usages can be satisfied.
 225
 226
 227 .. _resource_create:
 228
 229 resource_create
 230 ^^^^^^^^^^^^^^^
 231
 232 Create a new resource from a template.
 233 The following fields of the pipe_resource must be specified in the template:
 234
 235 target
 236
 237 format
 238
 239 width0
 240
 241 height0
 242
 243 depth0
 244
 245 last_level
 246
 247 nr_samples
 248
 249 usage
 250
 251 bind
 252
 253 flags
 254
 255
 256
 257 resource_destroy
 258 ^^^^^^^^^^^^^^^^
 259
 260 Destroy a resource. A resource is destroyed if it has no more references.
 261