summaryrefslogtreecommitdiff
path: root/src/gallium/docs/source/screen.rst
blob: e78634e59e9077a558f7e54ecc6d7b645474d9db (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
Screen
======

A screen is an object representing the context-independent part of a device.

Useful Flags
------------

.. _pipe_cap:

PIPE_CAP
^^^^^^^^

Pipe capabilities help expose hardware functionality not explicitly required
by Gallium. For floating-point values, use :ref:`get_paramf`, and for boolean
or integer values, use :ref:`get_param`.

The integer capabilities:

* ``MAX_TEXTURE_IMAGE_UNITS``: The maximum number of samplers available.
* ``NPOT_TEXTURES``: Whether :term:`NPOT` textures may have repeat modes,
  normalized coordinates, and mipmaps.
* ``TWO_SIDED_STENCIL``: Whether the stencil test can also affect back-facing
  polygons.
* ``GLSL``: Deprecated.
* ``DUAL_SOURCE_BLEND``: Whether dual-source blend factors are supported. See
  :ref:`Blend` for more information.
* ``ANISOTROPIC_FILTER``: Whether textures can be filtered anisotropically.
* ``POINT_SPRITE``: Whether point sprites are available.
* ``MAX_RENDER_TARGETS``: The maximum number of render targets that may be
  bound.
* ``OCCLUSION_QUERY``: Whether occlusion queries are available.
* ``TEXTURE_SHADOW_MAP``: XXX
* ``MAX_TEXTURE_2D_LEVELS``: The maximum number of mipmap levels available
  for a 2D texture.
* ``MAX_TEXTURE_3D_LEVELS``: The maximum number of mipmap levels available
  for a 3D texture.
* ``MAX_TEXTURE_CUBE_LEVELS``: The maximum number of mipmap levels available
  for a cubemap.
* ``TEXTURE_MIRROR_CLAMP``: Whether mirrored texture coordinates with clamp
  are supported.
* ``TEXTURE_MIRROR_REPEAT``: Whether mirrored repeating texture coordinates
  are supported.
* ``MAX_VERTEX_TEXTURE_UNITS``: The maximum number of samplers addressable
  inside the vertex shader. If this is 0, then the vertex shader cannot
  sample textures.
* ``TGSI_CONT_SUPPORTED``: Whether the TGSI CONT opcode is supported.
* ``BLEND_EQUATION_SEPARATE``: Whether alpha blend equations may be different
  from color blend equations, in :ref:`Blend` state.
* ``SM3``: Whether the vertex shader and fragment shader support equivalent
  opcodes to the Shader Model 3 specification. XXX oh god this is horrible
* ``MAX_PREDICATE_REGISTERS``: XXX
* ``MAX_COMBINED_SAMPLERS``: The total number of samplers accessible from
  the vertex and fragment shader, inclusive.
* ``MAX_CONST_BUFFERS``: Maximum number of constant buffers that can be bound
  to any shader stage using ``set_constant_buffer``. If 0 or 1, the pipe will
  only permit binding one constant buffer per shader, and the shaders will
  not permit two-dimensional access to constants.
* ``MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant buffer.
* ``INDEP_BLEND_ENABLE``: Whether per-rendertarget blend enabling and channel
  masks are supported. If 0, then the first rendertarget's blend mask is
  replicated across all MRTs.
* ``INDEP_BLEND_FUNC``: Whether per-rendertarget blend functions are
  available. If 0, then the first rendertarget's blend functions affect all
  MRTs.
* ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_UPPER_LEFT``: Whether the TGSI property
  FS_COORD_ORIGIN with value UPPER_LEFT is supported.
* ``PIPE_CAP_TGSI_FS_COORD_ORIGIN_LOWER_LEFT``: Whether the TGSI property
  FS_COORD_ORIGIN with value LOWER_LEFT is supported.
* ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_HALF_INTEGER``: Whether the TGSI
  property FS_COORD_PIXEL_CENTER with value HALF_INTEGER is supported.
* ``PIPE_CAP_TGSI_FS_COORD_PIXEL_CENTER_INTEGER``: Whether the TGSI
  property FS_COORD_PIXEL_CENTER with value INTEGER is supported.

The floating-point capabilities:

* ``MAX_LINE_WIDTH``: The maximum width of a regular line.
* ``MAX_LINE_WIDTH_AA``: The maximum width of a smoothed line.
* ``MAX_POINT_WIDTH``: The maximum width and height of a point.
* ``MAX_POINT_WIDTH_AA``: The maximum width and height of a smoothed point.
* ``MAX_TEXTURE_ANISOTROPY``: The maximum level of anisotropy that can be
  applied to anisotropically filtered textures.
* ``MAX_TEXTURE_LOD_BIAS``: The maximum :term:`LOD` bias that may be applied
  to filtered textures.
* ``GUARD_BAND_LEFT``, ``GUARD_BAND_TOP``, ``GUARD_BAND_RIGHT``,
  ``GUARD_BAND_BOTTOM``: XXX

XXX Is there a better home for this? vvv

If 0 is returned, the driver is not aware of multiple constant buffers,
supports binding of only one constant buffer, and does not support
two-dimensional CONST register file access in TGSI shaders.

If a value greater than 0 is returned, the driver can have multiple
constant buffers bound to shader stages. The CONST register file can
be accessed with two-dimensional indices, like in the example below.

DCL CONST[0][0..7]       # declare first 8 vectors of constbuf 0
DCL CONST[3][0]          # declare first vector of constbuf 3
MOV OUT[0], CONST[0][3]  # copy vector 3 of constbuf 0

For backwards compatibility, one-dimensional access to CONST register
file is still supported. In that case, the constbuf index is assumed
to be 0.

.. _pipe_buffer_usage:

PIPE_BUFFER_USAGE
^^^^^^^^^^^^^^^^^

These flags control buffer creation. Buffers may only have one role, so
care should be taken to not allocate a buffer with the wrong usage.

* ``PIXEL``: This is the flag to use for all textures.
* ``VERTEX``: A vertex buffer.
* ``INDEX``: An element buffer.
* ``CONSTANT``: A buffer of shader constants.

Buffers are inevitably abstracting the pipe's underlying memory management,
so many of their usage flags can be used to direct the way the buffer is
handled.

* ``CPU_READ``, ``CPU_WRITE``: Whether the user will map and, in the case of
  the latter, write to, the buffer. The convenience flag ``CPU_READ_WRITE`` is
  available to signify a read/write buffer.
* ``GPU_READ``, ``GPU_WRITE``: Whether the driver will internally need to
  read from or write to the buffer. The latter will only happen if the buffer
  is made into a render target.
* ``DISCARD``: When set on a map, the contents of the map will be discarded
  beforehand. Cannot be used with ``CPU_READ``.
* ``DONTBLOCK``: When set on a map, the map will fail if the buffer cannot be
  mapped immediately.
* ``UNSYNCHRONIZED``: When set on a map, any outstanding operations on the
  buffer will be ignored. The interaction of any writes to the map and any
  operations pending with the buffer are undefined. Cannot be used with
  ``CPU_READ``.
* ``FLUSH_EXPLICIT``: When set on a map, written ranges of the map require
  explicit flushes using :ref:`buffer_flush_mapped_range`. Requires
  ``CPU_WRITE``.

.. _pipe_texture_usage:

PIPE_TEXTURE_USAGE
^^^^^^^^^^^^^^^^^^

These flags determine the possible roles a texture may be used for during its
lifetime. Texture usage flags are cumulative and may be combined to create a
texture that can be used as multiple things.

* ``RENDER_TARGET``: A color buffer or pixel buffer which will be rendered to.
* ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
* ``PRIMARY``: A front color buffer or scanout buffer.
* ``DEPTH_STENCIL``: A depth (Z) buffer or stencil buffer.  Gallium does
  not explicitly provide for stencil-only buffers, so any stencil buffer
  validated here is implicitly also a depth buffer.
* ``SAMPLER``: A texture that may be sampled from in a fragment or vertex
  shader.
* ``DYNAMIC``: A texture that will be mapped frequently.


PIPE_TEXTURE_GEOM
^^^^^^^^^^^^^^^^^

These flags are used when querying whether a particular pipe_format is
supported by the driver (with the `is_format_supported` function).
Some formats may only be supported for certain kinds of textures.
For example, a compressed format might only be used for POT textures.

* ``PIPE_TEXTURE_GEOM_NON_SQUARE``: The texture may not be square
* ``PIPE_TEXTURE_GEOM_NON_POWER_OF_TWO``: The texture dimensions may not be
  powers of two.


Methods
-------

XXX moar; got bored

get_name
^^^^^^^^

Returns an identifying name for the screen.

get_vendor
^^^^^^^^^^

Returns the screen vendor.

.. _get_param:

get_param
^^^^^^^^^

Get an integer/boolean screen parameter.

**param** is one of the :ref:`PIPE_CAP` names.

.. _get_paramf:

get_paramf
^^^^^^^^^^

Get a floating-point screen parameter.

**param** is one of the :ref:`PIPE_CAP` names.

context_create
^^^^^^^^^^^^^^

Create a pipe_context.

**priv** is private data of the caller, which may be put to various
unspecified uses, typically to do with implementing swapbuffers
and/or front-buffer rendering.

is_format_supported
^^^^^^^^^^^^^^^^^^^

See if a format can be used in a specific manner.

**usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.

Returns TRUE if all usages can be satisfied.

.. note::

   ``PIPE_TEXTURE_USAGE_DYNAMIC`` is not a valid usage.

.. _texture_create:

texture_create
^^^^^^^^^^^^^^

Given a template of texture setup, create a buffer and texture.

texture_blanket
^^^^^^^^^^^^^^^

Like :ref:`texture_create`, but use a supplied buffer instead of creating a
new one.

texture_destroy
^^^^^^^^^^^^^^^

Destroy a texture. The buffer backing the texture is destroyed if it has no
more references.

buffer_map
^^^^^^^^^^

Map a buffer into memory.

**usage** is a bitmask of :ref:`PIPE_BUFFER_USAGE` flags.

Returns a pointer to the map, or NULL if the mapping failed.

buffer_map_range
^^^^^^^^^^^^^^^^

Map a range of a buffer into memory.

The returned map is always relative to the beginning of the buffer, not the
beginning of the mapped range.

.. _buffer_flush_mapped_range:

buffer_flush_mapped_range
^^^^^^^^^^^^^^^^^^^^^^^^^

Flush a range of mapped memory into a buffer.

The buffer must have been mapped with ``PIPE_BUFFER_USAGE_FLUSH_EXPLICIT``.

**usage** is a bitmask of :ref:`PIPE_BUFFER_USAGE` flags.

buffer_unmap
^^^^^^^^^^^^

Unmap a buffer from memory.

Any pointers into the map should be considered invalid and discarded.