summaryrefslogtreecommitdiff
path: root/dri3proto.txt
blob: 3f516f72f80f9adf8d50b12b3efdb48358154f7e (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
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
			  The DRI3 Extension
			     Version 1.0
			       2013-6-4
      
			    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 Present 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.

DRI3 also includes a mechanism to translate between Linux Futexes
and X Sync extension Fences. This provides a synchronization mechanism
which can be used to serialize access to shared render buffers.

1.1. Acknowledgments

Eric Anholt <eric@anholt.net>
Dave Airlie <airlied@redhat.com>
Kristian Høgsberg <krh@bitplanet.net>
James Jones <janomes@nvidia.com>
Arthur Huillet <arthur.huillet@free.fr>

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

2. Data Types

The DRI3 extension uses the RandR extension Provider data type to
select among multiple GPUs on a single screen and the Sync extension
fence object to provide graphics object synchronization.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

4. Errors

DRI3 defines no errors.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

5. Events

DRI3 defines no events.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

6. Protocol Types

DRI3 defines no new protocol types.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

7. Extension Initialization

The name of this extension is "DRI3"

┌───
    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
	provider: PROVIDER
      ▶
	nfd: CARD8
	device: FD
└───
	Errors: Drawable, Value, Match

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

	The file descriptor for the device is returned in
	'device'. 'nfd' will be set to one (this is strictly a
	convenience for XCB which otherwise would need
	request-specific information about how many file descriptors
	were associated with this reply).

┌───
    DRI3PixmapFromBuffer
	pixmap: PIXMAP
	drawable: DRAWABLE
	size: CARD32
	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'. Changes to pixmap will be visible in that
	direct rendered object and changes to the direct rendered
	object will be visible in the pixmap.

	'size' specifies the total size of the buffer bytes. 'width',
	'height' describe the geometry (in pixels) of the underlying
	buffer. 'stride' specifies the number of bytes per scanline in
	the buffer. The pixels within the buffer are not required to
	be arranged in a simple linear fashion, but 'size' will be at
	least 'height' * 'stride'.

	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
      ▶
	nfd: CARD8
	size: CARD32
	width, height, stride: CARD16
	depth, bpp: CARD8
	buffer: FD
└───
	Errors: Pixmap, Match

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

	'size' specifies the total size of the buffer bytes. 'width',
	'height' describe the geometry (in pixels) of the underlying
	buffer. 'stride' specifies the number of bytes per scanline in
	the buffer. The pixels within the buffer are not required to
	be arranged in a simple linear fashion, but 'size' will be at
	least 'height' * 'stride'.

	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.

┌───
    DRI3FenceFromFD
	drawable: DRAWABLE
	fence: FENCE
	initially-triggered: BOOL
	fd: FD
└───
	Errors: IDchoice, Drawable

	Creates a Sync extension Fence that provides the regular Sync
	extension semantics along with a file descriptor that provides
	a device-specific mechanism to manipulate the fence directly.
	Details about the mechanism used with this file descriptor are
	outside the scope of the DRI3 extension.

┌───
    DRI3FDFromFence
	drawable: DRAWABLE
	fence: FENCE
      ▶
	fd: FD
└───
	Errors: IDchoice, Drawable, Match

	Given a Sync extension Fence that provides the regular Sync
	extension semantics, returns a file descriptor that provides a
	device-specific mechanism to manipulate the fence directly.
	Details about the mechanism used with this file descriptor are
	outside the scope of the DRI3 extension. 'drawable' must be
	associated with a direct rendering device that 'fence' can
	work with, otherwise a Match error results.


			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

9. Extension Events

DRI3 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 is both an application interface and an X extension. OpenGL
applications using the GLX API will use the GLX extension, DRI3 and
Present when doing direct rendering.

11.2 Present

The Present 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.

Present 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

None.

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	CARD32			driver type
	4	PROVIDER		provider
      ▶	
	1	1			Reply
        1	1			nfd
	2	CARD16			sequence number
	4	(n + p) / 4		reply length
	4	n			driver name length (n)
	20				unused
	n	CARD8			driver name
	p				unused, p=pad(n)

	0	FD			device
└───

┌───
    DRI3PixmapFromBuffer
	1	CARD8			major opcode
	1	2			DRI3 opcode
	2	6			length
	4	Pixmap			pixmap
	4	Drawable		drawable
	4	CARD32			size
	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	2			length
	4	Pixmap			pixmap
      ▶	
	1	1			Reply
        1	1			nfd
	2	CARD16			sequence number
	4	0			reply length
	4	CARD32			size
	2	CARD16			width
	2	CARD16			height
	2	CARD16			stride
	1	CARD8			depth
	1	CARD8			bpp
	12				unused

	0	FD			buffer
└───

┌───
    DRI3FenceFromFD
	1	CARD8			major opcode
	1	4			DRI3 opcode
	2	4			length
	4	Drawable		drawable
	4	Fence			fence
	1	BOOL			initially triggered
	3				unused

	0	FD			fence fd
└───

┌───
    DRI3FDFromFence
	1	CARD8			major opcode
	1	5			DRI3 opcode
	2	3			length
	4	Drawable		drawable
	4	Fence			fence
      ▶	
	1	1			Reply
        1	1			nfd
	2	CARD16			sequence number
	4	0			reply length
	24				unused

	0	FD			fence fd
└───

A.3 Protocol Events

The DRI3 extension defines no events.

A.4 Protocol Errors

The DRI3 extension defines no errors.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄