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 * ``PIPE_CAP_NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
  26   normalized coordinates, and mipmaps.
  27 * ``PIPE_CAP_TWO_SIDED_STENCIL``: Whether the stencil test can also affect back-facing
  28   polygons.
  29 * ``PIPE_CAP_DUAL_SOURCE_BLEND``: Whether dual-source blend factors are supported. See
  30   :ref:`Blend` for more information.
  31 * ``PIPE_CAP_ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
  32 * ``PIPE_CAP_POINT_SPRITE``: Whether point sprites are available.
  33 * ``PIPE_CAP_MAX_RENDER_TARGETS``: The maximum number of render targets that may be
  34   bound.
  35 * ``PIPE_CAP_OCCLUSION_QUERY``: Whether occlusion queries are available.
  36 * ``PIPE_CAP_TIMER_QUERY``: Whether timer queries are available.
  37 * ``PIPE_CAP_TEXTURE_SHADOW_MAP``: indicates whether the fragment shader hardware
  38   can do the depth texture / Z comparison operation in TEX instructions
  39   for shadow testing.
  40 * ``PIPE_CAP_TEXTURE_SWIZZLE``: Whether swizzling through sampler views is
  41   supported.
  42 * ``PIPE_CAP_MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
  43   for a 2D texture.
  44 * ``PIPE_CAP_MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
  45   for a 3D texture.
  46 * ``PIPE_CAP_MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
  47   for a cubemap.
  48 * ``PIPE_CAP_TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
  49   are supported.
  50 * ``PIPE_CAP_BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
  51   from color blend equations, in :ref:`Blend` state.
  52 * ``PIPE_CAP_SM3``: Whether the vertex shader and fragment shader support equivalent
  53   opcodes to the Shader Model 3 specification. XXX oh god this is horrible
  54 * ``PIPE_CAP_MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
  55   the vertex and fragment shader, inclusive.
  56 * ``PIPE_CAP_INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
  57   masks are supported. If 0, then the first rendertarget's blend mask is
  58   replicated across all MRTs.
  59 * ``PIPE_CAP_INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
  60   available. If 0, then the first rendertarget's blend functions affect all
  61   MRTs.
  62 * ``PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE``: Whether clearing only depth or only
  63   stencil in a combined depth-stencil buffer is supported.
  64 * ``PIPE_CAP_MAX_TEXTURE_ARRAY_LAYERS``: The maximum number of texture array
  65   layers supported. If 0, the array textures are not supported at all and
  66   the ARRAY texture targets are invalid.
  67 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
  68   FS_COORD_ORIGIN with value UPPER_LEFT is supported.
  69 * ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
  70   FS_COORD_ORIGIN with value LOWER_LEFT is supported.
  71 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
  72   property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
  73 * ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
  74   property FS_COORD_PIXEL_CENTER with value INTEGER is supported.
  75
  76
  77 .. _pipe_capf:
  78
  79 PIPE_CAPF_*
  80 ^^^^^^^^^^^^^^^^
  81
  82 The floating-point capabilities are:
  83
  84 * ``PIPE_CAPF_MAX_LINE_WIDTH``: The maximum width of a regular line.
  85 * ``PIPE_CAPF_MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
  86 * ``PIPE_CAPF_MAX_POINT_WIDTH``: The maximum width and height of a point.
  87 * ``PIPE_CAPF_MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
  88 * ``PIPE_CAPF_MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
  89   applied to anisotropically filtered textures.
  90 * ``PIPE_CAPF_MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
  91   to filtered textures.
  92 * ``PIPE_CAPF_GUARD_BAND_LEFT``,
  93   ``PIPE_CAPF_GUARD_BAND_TOP``,
  94   ``PIPE_CAPF_GUARD_BAND_RIGHT``,
  95   ``PIPE_CAPF_GUARD_BAND_BOTTOM``: TODO
  96
  97
  98 .. _pipe_shader_cap:
  99
 100 PIPE_SHADER_CAP_*
 101 ^^^^^^^^^^^^^^^^^
 102
 103 These are per-shader-stage capabitity queries. Different shader stages may
 104 support different features.
 105
 106 * ``PIPE_SHADER_CAP_MAX_INSTRUCTIONS``: The maximum number of instructions.
 107 * ``PIPE_SHADER_CAP_MAX_ALU_INSTRUCTIONS``: The maximum number of arithmetic instructions.
 108 * ``PIPE_SHADER_CAP_MAX_TEX_INSTRUCTIONS``: The maximum number of texture instructions.
 109 * ``PIPE_SHADER_CAP_MAX_TEX_INDIRECTIONS``: The maximum number of texture indirections.
 110 * ``PIPE_SHADER_CAP_MAX_CONTROL_FLOW_DEPTH``: The maximum nested control flow depth.
 111 * ``PIPE_SHADER_CAP_MAX_INPUTS``: The maximum number of input registers.
 112 * ``PIPE_SHADER_CAP_MAX_CONSTS``: The maximum number of constants.
 113 * ``PIPE_SHADER_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
 114   to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
 115   only permit binding one constant buffer per shader, and the shaders will
 116   not permit two-dimensional access to constants.
 117
 118 If a value greater than 0 is returned, the driver can have multiple
 119 constant buffers bound to shader stages. The CONST register file can
 120 be accessed with two-dimensional indices, like in the example below.
 121
 122 DCL CONST[0][0..7]       # declare first 8 vectors of constbuf 0
 123 DCL CONST[3][0]          # declare first vector of constbuf 3
 124 MOV OUT[0], CONST[0][3]  # copy vector 3 of constbuf 0
 125
 126 For backwards compatibility, one-dimensional access to CONST register
 127 file is still supported. In that case, the constbuf index is assumed
 128 to be 0.
 129
 130 * ``PIPE_SHADER_CAP_MAX_TEMPS``: The maximum number of temporary registers.
 131 * ``PIPE_SHADER_CAP_MAX_ADDRS``: The maximum number of address registers.
 132 * ``PIPE_SHADER_CAP_MAX_PREDS``: The maximum number of predicate registers.
 133 * ``PIPE_SHADER_CAP_TGSI_CONT_SUPPORTED``: Whether the continue opcode is supported.
 134 * ``PIPE_SHADER_CAP_INDIRECT_INPUT_ADDR``: Whether indirect addressing
 135   of the input file is supported.
 136 * ``PIPE_SHADER_CAP_INDIRECT_OUTPUT_ADDR``: Whether indirect addressing
 137   of the output file is supported.
 138 * ``PIPE_SHADER_CAP_INDIRECT_TEMP_ADDR``: Whether indirect addressing
 139   of the temporary file is supported.
 140 * ``PIPE_SHADER_CAP_INDIRECT_CONST_ADDR``: Whether indirect addressing
 141   of the constant file is supported.
 142 * ``PIPE_SHADER_CAP_SUBROUTINES``: Whether subroutines are supported, i.e.
 143   BGNSUB, ENDSUB, CAL, and RET, including RET in the main block.
 144 * ``PIPE_SHADER_CAP_INTEGERS``: Whether integer opcodes are supported.
 145   If unsupported, only float opcodes are supported.
 146 * ``PIPE_SHADER_CAP_MAX_TEXTURE_SAMPLERS``: THe maximum number of texture
 147   samplers.
 148
 149
 150 .. _pipe_bind:
 151
 152 PIPE_BIND_*
 153 ^^^^^^^^^^^
 154
 155 These flags indicate how a resource will be used and are specified at resource
 156 creation time. Resources may be used in different roles
 157 during their lifecycle. Bind flags are cumulative and may be combined to create
 158 a resource which can be used for multiple things.
 159 Depending on the pipe driver's memory management and these bind flags,
 160 resources might be created and handled quite differently.
 161
 162 * ``PIPE_BIND_RENDER_TARGET``: A color buffer or pixel buffer which will be
 163   rendered to.  Any surface/resource attached to pipe_framebuffer_state::cbufs
 164   must have this flag set.
 165 * ``PIPE_BIND_DEPTH_STENCIL``: A depth (Z) buffer and/or stencil buffer. Any
 166   depth/stencil surface/resource attached to pipe_framebuffer_state::zsbuf must
 167   have this flag set.
 168 * ``PIPE_BIND_BLENDABLE``: Used in conjunction with PIPE_BIND_RENDER_TARGET to
 169   query whether a device supports blending for a given format.
 170   If this flag is set, surface creation may fail if blending is not supported
 171   for the specified format. If it is not set, a driver may choose to ignore
 172   blending on surfaces with formats that would require emulation.
 173 * ``PIPE_BIND_DISPLAY_TARGET``: A surface that can be presented to screen. Arguments to
 174   pipe_screen::flush_front_buffer must have this flag set.
 175 * ``PIPE_BIND_SAMPLER_VIEW``: A texture that may be sampled from in a fragment
 176   or vertex shader.
 177 * ``PIPE_BIND_VERTEX_BUFFER``: A vertex buffer.
 178 * ``PIPE_BIND_INDEX_BUFFER``: An vertex index/element buffer.
 179 * ``PIPE_BIND_CONSTANT_BUFFER``: A buffer of shader constants.
 180 * ``PIPE_BIND_TRANSFER_WRITE``: A transfer object which will be written to.
 181 * ``PIPE_BIND_TRANSFER_READ``: A transfer object which will be read from.
 182 * ``PIPE_BIND_CUSTOM``:
 183 * ``PIPE_BIND_SCANOUT``: A front color buffer or scanout buffer.
 184 * ``PIPE_BIND_SHARED``: A sharable buffer that can be given to another
 185   process.
 186
 187 .. _pipe_usage:
 188
 189 PIPE_USAGE_*
 190 ^^^^^^^^^^^^
 191
 192 The PIPE_USAGE enums are hints about the expected usage pattern of a resource.
 193
 194 * ``PIPE_USAGE_DEFAULT``: Expect many uploads to the resource, intermixed with draws.
 195 * ``PIPE_USAGE_DYNAMIC``: Expect many uploads to the resource, intermixed with draws.
 196 * ``PIPE_USAGE_STATIC``: Same as immutable (?)
 197 * ``PIPE_USAGE_IMMUTABLE``: Resource will not be changed after first upload.
 198 * ``PIPE_USAGE_STREAM``: Upload will be followed by draw, followed by upload, ...
 199
 200
 201 Methods
 202 -------
 203
 204 XXX to-do
 205
 206 get_name
 207 ^^^^^^^^
 208
 209 Returns an identifying name for the screen.
 210
 211 get_vendor
 212 ^^^^^^^^^^
 213
 214 Returns the screen vendor.
 215
 216 .. _get_param:
 217
 218 get_param
 219 ^^^^^^^^^
 220
 221 Get an integer/boolean screen parameter.
 222
 223 **param** is one of the :ref:`PIPE_CAP` names.
 224
 225 .. _get_paramf:
 226
 227 get_paramf
 228 ^^^^^^^^^^
 229
 230 Get a floating-point screen parameter.
 231
 232 **param** is one of the :ref:`PIPE_CAP` names.
 233
 234 context_create
 235 ^^^^^^^^^^^^^^
 236
 237 Create a pipe_context.
 238
 239 **priv** is private data of the caller, which may be put to various
 240 unspecified uses, typically to do with implementing swapbuffers
 241 and/or front-buffer rendering.
 242
 243 is_format_supported
 244 ^^^^^^^^^^^^^^^^^^^
 245
 246 Determine if a resource in the given format can be used in a specific manner.
 247
 248 **format** the resource format
 249
 250 **target** one of the PIPE_TEXTURE_x flags
 251
 252 **sample_count** the number of samples. 0 and 1 mean no multisampling,
 253 the maximum allowed legal value is 32.
 254
 255 **bindings** is a bitmask of :ref:`PIPE_BIND` flags.
 256
 257 **geom_flags** is a bitmask of PIPE_TEXTURE_GEOM_x flags.
 258
 259 Returns TRUE if all usages can be satisfied.
 260
 261 .. _resource_create:
 262
 263 resource_create
 264 ^^^^^^^^^^^^^^^
 265
 266 Create a new resource from a template.
 267 The following fields of the pipe_resource must be specified in the template:
 268
 269 **target** one of the pipe_texture_target enums.
 270 Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
 271 Modern APIs allow using buffers as shader resources.
 272
 273 **format** one of the pipe_format enums.
 274
 275 **width0** the width of the base mip level of the texture or size of the buffer.
 276
 277 **height0** the height of the base mip level of the texture
 278 (1 for 1D or 1D array textures).
 279
 280 **depth0** the depth of the base mip level of the texture
 281 (1 for everything else).
 282
 283 **array_size** the array size for 1D and 2D array textures.
 284 For cube maps this must be 6, for other textures 1.
 285
 286 **last_level** the last mip map level present.
 287
 288 **nr_samples** the nr of msaa samples. 0 (or 1) specifies a resource
 289 which isn't multisampled.
 290
 291 **usage** one of the PIPE_USAGE flags.
 292
 293 **bind** bitmask of the PIPE_BIND flags.
 294
 295 **flags** bitmask of PIPE_RESOURCE_FLAG flags.
 296
 297
 298
 299 resource_destroy
 300 ^^^^^^^^^^^^^^^^
 301
 302 Destroy a resource. A resource is destroyed if it has no more references.
 303