← Back to branch summary

~ubuntu-branches/ubuntu/precise/mesa/precise-updates

« back to all changes in this revision

Viewing changes to src/gallium/docs/source/screen.rst

  • Committer: Package Import Robot
  • Author(s): Robert Hooker
  • Date: 2012-02-02 12:05:48 UTC
  • mfrom: (1.7.1) (3.3.27 sid)
  • Revision ID: package-import@ubuntu.com-20120202120548-nvkma85jq0h4coix
Tags: 8.0~rc2-0ubuntu4
Drop drisearchdir handling, it is no longer needed with multiarch
and dri-alternates being removed.

Show diffs side-by-side

added added

removed removed

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