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
|
Screen
======
A screen is an object representing the context-independent part of a device.
Useful Flags
------------
.. _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 colorbuffer or pixelbuffer.
* ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
* ``PRIMARY``: A frontbuffer or scanout buffer.
* ``DEPTH_STENCIL``: A depthbuffer, stencilbuffer, or Z buffer. Gallium does
not explicitly provide for stencil-only buffers, so any stencilbuffer
validated here is implicitly also a depthbuffer.
* ``SAMPLER``: A texture that may be sampled from in a fragment or vertex
shader.
* ``DYNAMIC``: A texture that will be mapped frequently.
Methods
-------
XXX moar; got bored
get_name
^^^^^^^^
Returns an identifying name for the screen.
get_vendor
^^^^^^^^^^
Returns the screen vendor.
get_param
^^^^^^^^^
Get an integer/boolean screen parameter. Valid parameter names include.
* ``PIPE_CAP_MAX_CONST_BUFFERS``: Maximum number of constant buffers that
can be bound to any shader stage using ``set_constant_buffer``.
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_CAP_MAX_CONST_BUFFER_SIZE``: Maximum byte size of a single constant
buffer.
get_paramf
^^^^^^^^^^
Get a floating-point screen parameter.
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_TEXTURE_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_TEXTURE_USAGE` flags.
buffer_unmap
^^^^^^^^^^^^
Unmap a buffer from memory.
Any pointers into the map should be considered invalid and discarded.
|
