mirror of
https://gitlab.freedesktop.org/xorg/proto/xorgproto.git
synced 2025-12-20 05:50:13 +01:00
315 lines
6.9 KiB
Text
315 lines
6.9 KiB
Text
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.
|
|
|
|
❄ ❄ ❄ ❄ ❄ ❄ ❄
|