xorg-xorgproto/dri3proto.txt

			  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>

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

2. Data Types

DRI3EVENTID { XID }

	Defines a unique event delivery target for DRI3
	events. Multiple event IDs can be allocated to provide
	multiple distinct event delivery contexts.

DRI3EVENTMASK { DRI3ConfigureNotifyMask }

The DRI3 extension also 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

No errors are defined by the DRI3 extension.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

5. Events

DRI3 adds a ConfigureNotify event to inform clients about window
configuration changes which can affect the allocation of
window-related direct rendered buffers.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

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"

┌───
    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 'driver'. 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 may not 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 may not 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.

┌───
    DRI3SelectInput
	eventContext: DRI3EVENTID
	window: WINDOW
	eventMask: SETofDRI3EVENT
└───
	Errors: Window, Value, Match, IDchoice

	Selects the set of DRI3 events to be delivered for the
	specified window and event context. DRI3SelectInput can
	create, modifiy or delete event contexts. An event context is
	associated with a specific window; using an existing event
	context with a different window generates a Match error.

	If eventContext specifies an existing event context, then if
	eventMask is empty, DRI3SelectInput deletes the specified
	context, otherwise the specified event context is changed to
	select a different set of events.

	If eventContext is an unused XID, then if eventMask is empty
	no operation is performed. Otherwise, a new event context is
	created selecting the specified events.

┌───
    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.


			     ❄ ❄ ❄  ❄  ❄ ❄ ❄ 

9. Extension Events

DRI3ConfigureNotify is sent if DRI3SelectInput has requested it.
DRI3ConfigureNotify events are XGE events and so do not have a unique
event ID.

┌───
    DRI3ConfigureNotify
	type: CARD8			XGE event type (35)
	extension: CARD8		DRI3 extension request number
	length: CARD16			2
	evtype: CARD16			DRI3_ConfigureNotify
	eventID: DRI3EVENTID
	window: WINDOW
	x: INT16
	y: INT16
	width: CARD16
	height: CARD16
	off_x: INT16
	off_y: INT16
	pixmap_width: CARD16
	pixmap_height: CARD16
	pixmap_flags: CARD32
└───

	'x' and 'y' are the parent-relative location of 'window'. 

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄

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

┌───
    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	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
└───

┌───
    DRI3SelectInput
	1	CARD8			major opcode
	1	4			DRI3 opcode
	2	3			length
	4	Window			window
	4	CARD32			eid
	4	CARD32			event mask
└───

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

	0	FD			fence fd
└───

A.3 Protocol Events

┌───
    RRScreenChangeNotify
	1	35			XGE
	1	CARD8			DRI3 extension opcode
	2	CARD16			sequence number
	4	2			length
	2	0			DRI3ConfigureNotify
	2				unused
	4	CARD32			event id
	4	Window			window
	2	INT16			x
	2	INT16			y
	2	CARD16			width
	2	CARD16			height
	2	INT16			off x
	2	INT16			off y
	2	CARD16			pixmap width
	2	CARD16			pixmap height
	4	CARD32			pixmap flags
└───

A.4 Protocol Errors

The DRI3 extension defines no errors.

			     ❄ ❄ ❄  ❄  ❄ ❄ ❄