[PATCH xorgproto v8 01/14] dri3: Add modifier/multi-plane requests, bump to v1.2
Daniel Stone
daniels at collabora.com
Wed Feb 28 01:16:27 UTC 2018
From: Louis-Francis Ratté-Boulianne <lfrb at collabora.com>
DRI3 version 1.2 adds support for explicit format modifiers,
including multi-planar buffers.
Signed-off-by: Daniel Stone <daniels at collabora.com>
Signed-off-by: Louis-Francis Ratté-Boulianne <lfrb at collabora.com>
---
dri3proto.pc.in | 2 +-
dri3proto.txt | 319 +++++++++++++++++++++++++++++++++++--
include/X11/extensions/dri3proto.h | 86 +++++++++-
meson.build | 2 +-
4 files changed, 396 insertions(+), 13 deletions(-)
diff --git a/dri3proto.pc.in b/dri3proto.pc.in
index 6d81d07..e42d60e 100644
--- a/dri3proto.pc.in
+++ b/dri3proto.pc.in
@@ -5,5 +5,5 @@ includedir=@includedir@
Name: DRI3Proto
Description: DRI3 extension headers
-Version: 1.0
+Version: 1.2
Cflags: -I${includedir}
diff --git a/dri3proto.txt b/dri3proto.txt
index dac11d3..94322e7 100644
--- a/dri3proto.txt
+++ b/dri3proto.txt
@@ -1,16 +1,22 @@
The DRI3 Extension
- Version 1.0
- 2013-6-4
-
+ Version 1.2
+ 2018-02-28
+
Keith Packard
keithp at keithp.com
Intel Corporation
+ Daniel Stone
+ daniels at collabora.com
+ Collabora
+
+
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.
+a complete direct rendering solution for hardware-accelerated devices
+such as GPUs is provided.
The direct rendered buffers are passed across the protocol via
standard POSIX file descriptor passing mechanisms. On Linux, these
@@ -25,8 +31,9 @@ which can be used to serialize access to shared render buffers.
Eric Anholt <eric at anholt.net>
Dave Airlie <airlied at redhat.com>
Kristian Høgsberg <krh at bitplanet.net>
-James Jones <janomes at nvidia.com>
+James Jones <jajones at nvidia.com>
Arthur Huillet <arthur.huillet at free.fr>
+Louis-Francis Ratté-Boulianne <lfrb at collabora.com>
❄ ❄ ❄ ❄ ❄ ❄ ❄
@@ -117,9 +124,10 @@ The name of this extension is "DRI3"
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.
+ with 'buffer' and the screen associated with 'drawable'.
+ 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
@@ -137,6 +145,9 @@ The name of this extension is "DRI3"
If depth or bpp are not supported by the screen, a Value error
is returned.
+ For information on synchronization of buffer access between
+ the client and the X server, please see section 12.
+
┌───
DRI3BufferFromPixmap
pixmap: PIXMAP
@@ -167,6 +178,9 @@ The name of this extension is "DRI3"
If buffer cannot be used with the screen associated with
drawable, a Match error is returned.
+ For information on synchronization of buffer access between
+ the client and the X server, please see section 12.
+
┌───
DRI3FenceFromFD
drawable: DRAWABLE
@@ -182,6 +196,9 @@ The name of this extension is "DRI3"
Details about the mechanism used with this file descriptor are
outside the scope of the DRI3 extension.
+ For information on synchronization of buffer access between
+ the client and the X server, please see section 12.
+
┌───
DRI3FDFromFence
drawable: DRAWABLE
@@ -199,8 +216,163 @@ The name of this extension is "DRI3"
associated with a direct rendering device that 'fence' can
work with, otherwise a Match error results.
+ For information on synchronization of buffer access between
+ the client and the X server, please see section 12.
- ❄ ❄ ❄ ❄ ❄ ❄ ❄
+┌───
+ DRI3GetSupportedModifiers
+ window: WINDOW
+ depth: CARD8
+ bpp: CARD8
+ ▶
+ num_window_modifiers: CARD32
+ num_screen_modifiers: CARD32
+ window_modifiers: ListOfCARD64
+ screen_modifiers: ListOfCARD64
+└───
+ Errors: Window, Match
+
+ Return supported DRM FourCC modifiers for the specified
+ 'window'.
+
+ The first list of 'window_modifiers' contains a set of
+ modifiers which the server considers optimal for the window's
+ current configuration. Using these modifiers to allocate, even
+ if locally suboptimal to the client driver, may result in a
+ more optimal display pipeline, e.g. by avoiding composition.
+
+ The second list of 'screen_modifiers', is the total set of
+ modifiers which are acceptable for use on the Screen associated
+ with 'window'. This set of modifiers will not change over the
+ lifetime of the client. Using this set of modifiers to allocate
+ may not result in a globally optimal pipeline, if separate
+ 'window_modifiers' are available.
+
+ It is expected that a client calling this request will obtain
+ the modifiers for a particular window, allocate buffers using
+ the preferred modifier set as described above, create a Pixmap
+ referring to the storage of those buffers using the
+ DRI3BuffersFromPixmap request, then make the content visible
+ in the storage of those buffers visible with a request such as
+ the Present extension's PresentPixmap.
+
+ The meaning of any modifier is canonically defined in
+ drm_fourcc.h.
+
+┌───
+ DRI3PixmapFromBuffers
+ pixmap: PIXMAP
+ window: WINDOW
+ num_buffers: CARD8
+ width, height: CARD16
+ stride0, offset0: CARD32
+ stride1, offset1: CARD32
+ stride2, offset2: CARD32
+ stride3, offset3: CARD32
+ depth, bpp: CARD8
+ modifier: CARD64
+ buffers: ListOfFD
+└───
+ Errors: Alloc, Window, IDChoice, Value, Match
+
+ Creates a pixmap for the direct rendering object associated
+ with 'buffers' and the screen associated with 'window'.
+ Changes to pixmap will be visible in that direct rendered
+ object and changes to the direct rendered object will be
+ visible in the pixmap. The pixmap will be available for
+ presentation to the window.
+
+ In contrast to PixmapFromBuffer, multiple buffers may be
+ combined to specify a single logical source for pixel
+ sampling: 'num_buffers' may be set from 1 (single buffer,
+ akin to PixmapFromBuffer) to 4. This is the number of file
+ descriptors which will be sent with this request; one per
+ buffer.
+
+ Modifiers allow explicit specification of non-linear sources,
+ such as tiled or compressed buffers. The combination of bpp,
+ depth, and modifier allows unambiguous declaration of the
+ buffer layout in a manner defined by the DRM tokens.
+
+ If 'modifier' is DRM_FORMAT_MOD_INVALID, the client does
+ not have information on the buffer layout. In this case, the
+ buffer may only have a single plane. The driver may make its
+ own inference through unspecified means to determine the exact
+ buffer layout, however this is neither required nor defined
+ by the specification, and is considered an implementation
+ detail of the particular driver.
+
+ 'width' and 'height' describe the geometry (in pixels) of the
+ logical pixel-sample source.
+
+ 'strideN' and 'offsetN' define the number of bytes per logical
+ scanline, and the distance in bytes from the beginning of the
+ buffer passed for that plane until the start of the sample
+ source for that plane, respectively for plane N. If the plane
+ is not used according to the format and modifier specification,
+ both values for that plane must be zero.
+
+ Precisely how any additional information about the buffer (such
+ as memory placement) is shared is outside the scope of this
+ extension.
+
+ If the buffer(s) cannot be used with the screen associated with
+ 'window', a Match error is returned.
+
+ If the bpp, depth, and modifier combination is not supported by
+ the screen, a Value error is returned.
+
+ For information on synchronization of buffer access between
+ the client and the X server, please see section 12.
+
+┌───
+ DRI3BuffersFromPixmap
+ pixmap: PIXMAP
+ ▶
+ nfd: CARD8
+ width, height: CARD16
+ depth, bpp: CARD8
+ modifier: CARD64
+ strides: ListOfCARD32
+ offsets: ListOfCARD32
+ buffers: ListOfFD
+└───
+ Errors: Pixmap, Match
+
+ Returns direct rendering objects associated with 'pixmap'.
+ Changes to 'pixmap' will be visible in the direct rendered
+ objects and changes to the direct rendered objects will be
+ visible in 'pixmap' after flushing and synchronization.
+
+ 'width' and 'height' describe the geometry (in pixels) of the
+ logical pixel-sample source from combining the direct rendering
+ objects.
+
+ See PixmapFromBuffers for more details on DRM modifiers usage.
+
+ 'nfd' describes the number of buffers returned for the pixmap,
+ which must be combined together according to 'depth', 'bpp', and
+ 'modifier'.
+
+ For each buffer, there is an entry in the 'strides',
+ 'offsets', and 'buffers' list. 'buffer' contains a single file
+ descriptor referring to the buffer. 'stride' specifies the
+ number of bytes per logical scanline for this plane, and
+ 'offset' specifies the distance in bytes from the beginning
+ of 'buffer' until the start of the sample source for that
+ plane.
+
+ Precisely how any additional information about the buffer is
+ shared is outside the scope of this extension.
+
+ If buffers cannot be exported from the the screen associated
+ with 'pixmap', a Match error is returned.
+
+ For information on synchronization of buffer access between
+ the client and the X server, please see section 12.
+
+
+ ❄ ❄ ❄ ❄ ❄ ❄ ❄
9. Extension Events
@@ -214,6 +386,11 @@ The DRI3 extension is adapted from the DRI2 extension.
1.0: First published version
+ 1.1: Cosmetic changes
+
+ 1.2: Add GetSupportedModifiers,
+ PixmapFromBuffers, and BuffersFromPixmap requests.
+
❄ ❄ ❄ ❄ ❄ ❄ ❄
@@ -249,6 +426,57 @@ objects from the X server.
❄ ❄ ❄ ❄ ❄ ❄ ❄
+12. Synchronization
+
+Synchronization of access to buffers shared between processes is not
+currently explicitly controlled by this protocol.
+
+Without the use of additional extensions not defined by the DRI3
+protocol as of version 1.2, synchronization between multiple
+processes and contexts is considered to follow the implicit model.
+
+In this model, the driver is required to have a global view of
+access requests issued by all processes with a reference to the
+buffer, and control scheduling of all operations on that buffer,
+whether performed by the CPU or auxiliary hardware.
+
+The driver is responsible for enforcing a strict ordering to protect
+against write-after-read or read-after-write hazards, such that any
+reads requested by one process or context, are fulfilled before any
+writes requested by another process or context, as long as that read
+was definitively submitted before the write.
+
+A similar dependency exists for reads submitted after writes: the
+driver must ensure that the write is fully visible and coherent to
+the read request.
+
+As a purely illustrative example, if two processes share a buffer,
+where one process reads from a buffer using an OpenGL texture
+sampler and submits this work by calling 'glFlush', and the other
+process submits work to the driver to write to that buffer, the
+driver is responsible for ensuring that the results of the latter
+write are not visible to the texture sampler.
+
+The Sync fences provided by DRI3 control only this submission of
+work and ensuing global visibility of the requests, rather than the
+completion of the work within any hardware. To further the example
+above, a fence used to prevent any writes to the buffer before the
+sampler had completed access, the fence would be signaled when
+'glFlush' had been called, at which point the request has become
+globally visible to the driver's request-scheduling and
+synchronization mechanisms. The logical ordering of requests made
+by software has been preserved, and the driver then takes care
+to ensure that these requests are scheduled such they do not
+observe effects from requests made later in time.
+
+This presents a fully coherent in-order FIFO-like model across
+processes, where synchronzation is handled externally to the DRI3
+client with no explicit intervention.
+
+This restriction also applies for cross-device usage.
+
+ ❄ ❄ ❄ ❄ ❄ ❄ ❄
+
Appendix A. Protocol Encoding
Syntactic Conventions
@@ -367,6 +595,79 @@ A.2 Protocol Requests
0 FD fence fd
└───
+┌───
+ DRI3GetSupportedModifiers
+ 1 CARD8 major opcode
+ 1 7 DRI3 opcode
+ 2 3 length
+ 4 Window window
+ 1 CARD8 depth
+ 1 CARD8 bpp
+ 2 unused
+ ▶
+ 1 1 Reply
+ 1 0 unused
+ 2 CARD16 sequence number
+ 4 CARD32 reply length
+ 4 CARD32 num_window_modifiers
+ 4 CARD32 num_screen_modifiers
+ 16 unused
+
+ 4 ListOfCARD64 window_modifiers[num_window_modifiers]
+ 4 ListOfCARD64 screen_modifiers[num_screen_modifiers]
+└───
+
+┌───
+ DRI3PixmapFromBuffers
+ 1 CARD8 major opcode
+ 1 8 DRI3 opcode
+ 2 8 length
+ 4 Pixmap pixmap
+ 4 Window window
+ 1 CARD8 num_buffers
+ 3 unused
+ 2 CARD16 width
+ 2 CARD16 height
+ 4 CARD32 stride0
+ 4 CARD32 offset0
+ 4 CARD32 stride1
+ 4 CARD32 offset1
+ 4 CARD32 stride2
+ 4 CARD32 offset2
+ 4 CARD32 stride3
+ 4 CARD32 offset3
+ 1 CARD8 depth
+ 1 CARD8 bpp
+ 2 unused
+ 8 CARD64 modifier
+
+ 0 ListOfFD buffers[num_buffers]
+└───
+
+┌───
+ DRI3BuffersFromPixmap
+ 1 CARD8 major opcode
+ 1 9 DRI3 opcode
+ 2 2 length
+ 4 Pixmap pixmap
+ ▶
+ 1 1 Reply
+ 1 CARD8 nfd
+ 2 CARD16 sequence number
+ 4 CARD32 reply length
+ 2 CARD16 width
+ 2 CARD16 height
+ 4 CARD8 unused
+ 8 CARD64 modifier
+ 1 CARD8 depth
+ 1 CARD8 bpp
+ 6 unused
+
+ 0 ListOfFD buffer[nfd]
+ 4 ListOfCARD32 strides[nfd]
+ 4 ListOfCARD32 offsets[nfd]
+└───
+
A.3 Protocol Events
The DRI3 extension defines no events.
diff --git a/include/X11/extensions/dri3proto.h b/include/X11/extensions/dri3proto.h
index ceddee8..51b825d 100644
--- a/include/X11/extensions/dri3proto.h
+++ b/include/X11/extensions/dri3proto.h
@@ -25,7 +25,7 @@
#define DRI3_NAME "DRI3"
#define DRI3_MAJOR 1
-#define DRI3_MINOR 0
+#define DRI3_MINOR 2
#define DRI3NumberErrors 0
#define DRI3NumberEvents 0
@@ -37,7 +37,12 @@
#define X_DRI3FenceFromFD 4
#define X_DRI3FDFromFence 5
-#define DRI3NumberRequests 6
+/* v1.2 */
+#define xDRI3GetSupportedModifiers 6
+#define xDRI3PixmapFromBuffers 7
+#define xDRI3BuffersFromPixmap 8
+
+#define DRI3NumberRequests 9
typedef struct {
CARD8 reqType;
@@ -164,4 +169,81 @@ typedef struct {
#define sz_xDRI3FDFromFenceReply 32
+/* v1.2 */
+
+typedef struct {
+ CARD8 reqType;
+ CARD8 dri3ReqType;
+ CARD16 length B16;
+ CARD32 window B32;
+ CARD8 depth;
+ CARD8 bpp;
+ CARD16 pad10 B16;
+} xDRI3GetSupportedModifiersReq;
+#define sz_xDRI3GetSupportedModifiersReq 12
+
+typedef struct {
+ BYTE type; /* X_Reply */
+ CARD8 pad1;
+ CARD16 sequenceNumber B16;
+ CARD32 length B32;
+ CARD32 numWindowModifiers B32;
+ CARD32 numScreenModifiers B32;
+ CARD32 pad16 B32;
+ CARD32 pad20 B32;
+ CARD32 pad24 B32;
+ CARD32 pad28 B32;
+} xDRI3GetSupportedModifiersReply;
+#define sz_xDRI3GetSupportedModifiersReply 32
+
+typedef struct {
+ CARD8 reqType;
+ CARD8 dri3ReqType;
+ CARD16 length B16;
+ CARD32 pixmap B32;
+ CARD32 window B32;
+ CARD8 num_buffers; /* Number of file descriptors passed */
+ CARD8 pad13;
+ CARD16 pad14 B16;
+ CARD16 width B16;
+ CARD16 height B16;
+ CARD32 stride0 B32;
+ CARD32 offset0 B32;
+ CARD32 stride1 B32;
+ CARD32 offset1 B32;
+ CARD32 stride2 B32;
+ CARD32 offset2 B32;
+ CARD32 stride3 B32;
+ CARD32 offset3 B32;
+ CARD8 depth;
+ CARD8 bpp;
+ CARD16 pad54 B16;
+ CARD64 modifier;
+} xDRI3PixmapFromBuffersReq;
+#define sz_xDRI3PixmapFromBuffersReq 64
+
+typedef struct {
+ CARD8 reqType;
+ CARD8 dri3ReqType;
+ CARD16 length B16;
+ CARD32 pixmap B32;
+} xDRI3BuffersFromPixmapReq;
+#define sz_xDRI3BuffersFromPixmapReq 8
+
+typedef struct {
+ BYTE type; /* X_Reply */
+ CARD8 nfd; /* Number of file descriptors returned */
+ CARD16 sequenceNumber B16;
+ CARD32 length B32;
+ CARD16 width B16;
+ CARD16 height B16;
+ CARD32 pad12 B32;
+ CARD64 modifier;
+ CARD8 depth;
+ CARD8 bpp;
+ CARD16 pad26 B16;
+ CARD32 pad28 B32;
+} xDRI3BuffersFromPixmapReply;
+#define sz_xDRI3BuffersFromPixmapReply 32
+
#endif
diff --git a/meson.build b/meson.build
index 9511029..cb92280 100644
--- a/meson.build
+++ b/meson.build
@@ -30,7 +30,7 @@ pcs = [
['damageproto', '1.2.1'],
['dmxproto', '2.3.1'],
['dri2proto', '2.8'],
- ['dri3proto', '1.0'],
+ ['dri3proto', '1.2'],
['fixesproto', '5.0'],
['fontsproto', '2.1.3'],
['glproto', '1.4.17'],
--
2.14.3
More information about the xorg-devel
mailing list