summaryrefslogtreecommitdiff
path: root/dri3proto.txt
blob: bc3d0bf097c2ae3bff4261829ff2018a56a370d2 (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
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
			  The DRI3 Extension
			      Version 1.0
			      2013-2-19
      
			    Keith Packard
			  keithp@keithp.com
			  Intel Corporation

1. Introduction

The DRI3 extension provides mechanisms to translate between direct
rendered buffers and X pixmaps. When combined with the Swap extension,
a complete direct rendering solution for OpenGL is provided.

The direct rendered buffers are passed across the protocol via
standard POSIX file descriptor passing mechanisms. On Linux, these
buffers are DMA-BUF objects.

1.1. Acknowledgments

Eric Anholt <eric@anholt.net>
Dave Airlie <airlied@redhat.com>
Kristian Høgsberg <krh@bitplanet.net>

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

2. Data Types

The DRI3 extension uses the RandR extension Provider to select among
multiple GPUs on a single screen.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

4. Errors

No errors are defined by the DRI3 extension.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

5. Events

No events are defined by the DRI3 extension.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

6. Protocol Types

DRI3DRIVER { DRI3DriverDRI
	     DRI3DriverVDPAU }

	These values describe the type of driver the client will want
	to load.  The server sends back the name of the driver to use
	for the screen in question.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

7. Extension Initialization

The name of this extension is "DRI3" (third time is the charm?).

┌───
    DRI3QueryVersion
	client-major-version:	CARD32
	client-minor-version:	CARD32
      ▶
	major-version:		CARD32
	minor-version:		CARD32
└───

	The client sends the highest supported version to the server
	and the server sends the highest version it supports, but no
	higher than the requested version. Major versions changes can
	introduce incompatibilities in existing functionality, minor
	version changes introduce only backward compatible changes.
	It is the clients responsibility to ensure that the server
	supports a version which is compatible with its expectations.

	Backwards compatible changes included addition of new
	requests.


			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

8. Extension Requests

┌───
    DRI3Open
	drawable: DRAWABLE
	driverType: DRI3DRIVER
	provider: PROVIDER
      ▶
	nfd: CARD8
	driver: STRING
	device: FD
└───
	Errors: Drawable, Value, Match

	This requests that the X server open the direct rendering
	device associated with drawable, driverType and RandR
	provider. The provider must support SourceOutput or SourceOffload.

	The direct rendering library used to implement the specified
	driverType is returned in the driver value. The file
	descriptor for the device is returned in FD.

┌───
    DRI3PixmapFromBuffer
	pixmap: PIXMAP
	drawable: DRAWABLE
	width, height, stride: CARD16
	depth, bpp: CARD8
	buffer: FD
└───
	Errors: Alloc, Drawable, IDChoice, Value, Match

	Creates a pixmap for the direct rendering object associated
	with buffer. width, height and stride specify the geometry (in
	pixels) of the underlying buffer. The pixels within the buffer
	may not be arranged in a simple linear fashion, but the total
	byte size of the buffer must be height * stride * bpp /
	8. Precisely how any additional information about the buffer
	is shared is outside the scope of this extension.

	If buffer cannot be used with the screen associated with
	drawable, a Match error is returned.

	If depth or bpp are not supported by the screen, a Value error
	is returned.

┌───
    DRI3BufferFromPixmap
	pixmap: PIXMAP
      ▶
	depth: CARD8
	width, height, stride: CARD16
	depth, bpp: CARD8
	buffer: FD
└───
	Errors: Pixmap, Match

	Pass back a direct rendering object associated with
	pixmap. Future changes to pixmap will be visible in that
	direct rendered object.

	The pixel format and geometry of the buffer are returned along
	with a file descriptor referencing the underlying direct
	rendering object.

┌───
    DRI3GetSyncFenceFd
	fence: FENCE
	window: WINDOW
      ▶
	nfd: CARD8
	fd: FD
└───
	Errors: Fence, Match

	Pass back a shared memory segment associated with a sync fence
	object. Pass this fd to the XShmFence library to map and
	manipulate the fence.


			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

9. Extension Events

The DRI3 extension defines no events

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄

10. Extension Versioning

The DRI3 extension is adapted from the DRI2 extension.

	1.0: First published version

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄


11. Relationship with other extensions

As an extension designed to support other extensions, there is
naturally some interactions with other extensions.

11.1 GLX

GLX has no direct relation with DRI3, but a direct rendering OpenGL
application will presumably use both, and target 

11.2 Swap

The Swap extension provides a way to synchronize the display of pixmap
contents to the screen. When used in conjunction with DRI3, they
provide a complete direct rendering solution for OpenGL or other APIs.

11.3 DRI2

DRI3 provides similar functionality to the DRI2Connect and
DRI2GetBuffersWithFormat requests, however DRI3 uses file descriptors
to refer to the direct rendering device and buffers.

Swap and DRI3 are designed in conjunction to replace DRI2

11.2 XvMC / Xv

It might be nice to be able to reference YUV formatted direct rendered
objects from the X server.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄

Appendix A. Protocol Encoding

Syntactic Conventions

This document uses the same syntactic conventions as the core X
protocol encoding document.


A.1 Common Types

┌───
    DRI3DRIVER
	0x0	DRI3DriverDRI
	0x1	DRI3DriverVDPAU
└───

	Note that these match the DRI2 values.

A.2 Protocol Requests

┌───
    DRI3QueryVersion
	1	CARD8			major opcode
	1	0			DRI3 opcode
	2	3			length
	4	CARD32			major version
	4	CARD32			minor version
      ▶
	1	1			Reply
        1				unused
	2	CARD16			sequence number
	4	0			reply length
	4	CARD32			major version
        4	CARD32			minor version
	16				unused	
└───


┌───
    DRI3Open
	1	CARD8			major opcode
	1	1			DRI3 opcode
	2	4			length
	4	DRAWABLE		drawable
	4	PROVIDER		provider
	4	CARD32			driver type
      ▶	
	1	1			Reply
        1	CARD8			n
	2	CARD16			sequence number
	4	(n + p) / 4		reply length
	n	CARD8			driver name
	p				unused, p=pad(n)

	0	FD			device
└───

┌───
    DRI3PixmapFromBuffer
	1	CARD8			major opcode
	1	2			DRI3 opcode
	2	5			length
	4	Pixmap			pixmap
	4	Drawable		drawable
	2	CARD16			width
	2	CARD16			height
	2	CARD16			stride
	1	CARD8			depth
	1	CARD8			bpp

	0	FD			buffer
└───

┌───
    DRI3BufferFromPixmap
	1	CARD8			major opcode
	1	3			DRI3 opcode
	2				length
	4	Pixmap			pixmap
      ▶	
	1	1			Reply
        1				unused
	2	CARD16			sequence number
	4	0			reply length
	2	CARD16			width
	2	CARD16			height
	2	CARD16			stride
	1	CARD8			depth
	1	CARD8			bpp
	16				unused

	0	FD			buffer
└───


A.3 Protocol Events

The DRI3 extension defines no events

A.4 Protocol Errors

The Swap extension defines no errors.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄