Hi,
Here's an updated version of the DRi2 specification. I've added some
discussion points with ISSUE: in the spec. The new stuff here is the
XChangeWindowAttributes inspired DRI2CopyRegion, that'll let us better
extend it in the future. I clarified and simplified the auth stuff,
dropping the group concept. Also I'm still not convinced that the
swap pipe stuff can't just be an xorg.conf option, or maybe an randr
property on the display (preferred swap pipe or whatever).
And most of all, I'd like to keep the first version simple,
considering that we have a lot of options for extending this as we go.
Release early etc...
Kristian
The DRI2 Extension
Version 2.0
2008-09-04
Kristian Høgsberg
[EMAIL PROTECTED]
Red Hat, Inc
1. Introduction
The DRI2 extension is designed to associate and access auxillary
rendering buffers with an X drawable.
DRI2 is a essentially a helper extension to support implementation of
direct rendering drivers/libraries/technologies.
The main consumer of this extension will be a direct rendering OpenGL
driver, but the DRI2 extension is not designed to be OpenGL specific.
Direct rendering implementations of OpenVG, Xv, cairo and other
graphics APIs should find the functionality exposed by this extension
helpful and hopefully sufficient.
Relation to XF86DRI
1.1. Acknowledgements
Kevin E. Martin <[EMAIL PROTECTED]>
Keith Packard <[EMAIL PROTECTED]>
Eric Anholt <[EMAIL PROTECTED]>
Keith Whitwell <[EMAIL PROTECTED]>
Jerome Glisse <[EMAIL PROTECTED]>
Ian Romanick <[EMAIL PROTECTED]>
Michel Dänzer <[EMAIL PROTECTED]>
â â â â â â
2. DRI2 Concepts
2.1. Attachment points
Stolen from OpenGL FBOs, I guess.
2.2. Kernel rendering manager
This specification assumes a rendering architechture, where an
underlying kernel rendering manager that can provide 32 bit integer
handles to video memory buffers. These handles can be passed between
processes, which, through a direct rendering driver, submit rendering
to the kernel rendering manager, targeting and/or sourcing from these
buffers. This extension provides a means to communicate about such
buffers as associated with an X drawable.
The details of how the a direct rendering driver use the buffer names
and submit the rendering requests is outside the scope of this
specification. However, Appendix B does discuss implementation of
this specification on the Graphics Execution Manager (GEM).
2.3. Request ordering
No ordering between swap buffers and X rendering. X rendering to src
buffers will block if they have a vblank pending.
2.4 Authentication model
The purpose of the DRM authentication scheme is to grant access to the
kernel rendering manager buffers created by the X server if, and only
if, the client has access to the X server. This is achieved in a
three-step protocol:
1) The client gets a token from the kernel rendering manager
that uniquely identifies it. The token is a 32 bit integer.
2) The client passes the token to the X server in the
DRI2Authenticate request.
3) The X server authorizes the client by passing the token to
the kernel rendering manager.
A kernel rendering manager can choose not to implement any
authentication and just allow access to all buffers.
2.5 Rendering to the X front buffer
OpenGL allows the client to render to the front buffer, either by
using a single-buffered configuration or but explicitly setting the
draw buffer to GL_FRONT_LEFT. Not allowed!
The client must ask for a fake front buffer, render to that and then
use DRI2CopyRegion to copy contents back and forth between the fake
front buffer and the real front buffer. When X and direct rendering
to a front buffer is interleaved, it is the responsibility of the
application to synchronize access using glXWaitGL and glXWaitX. A
DRI2 implementation of direct rendering GLX, should use these enty
points to copy contents back and forth to as necessary to ensure
consistent rendering.
â â â â â â
3. Data Types
The server side region support specified in the Xfixes extension
version 2 is used in the CopyRegion request.
â â â â â â
4. Errors
Errors are sent using core X error reports.
Authenticate
The X server failed to authenticate the client.
â â â â â â
5. Protocol Types
DRI2ATTACHMENT { DRI2BufferFrontLeft
DRI2BufferBackLeft
DRI2BufferFrontRight
DRI2BufferBackRight
DRI2BufferDepth
DRI2BufferStencil
DRI2BufferAccum
DRI2BufferFakeFrontLeft
DRI2BufferFakeFrontRight }
These values describe various attachment points for DRI2
buffers.
DRI2BUFFER { attachment: CARD32
name: CARD32
pitch: CARD32
cpp: CARD32
flags: CARD32 }
The DRI2BUFFER describes an auxillary rendering buffer
associated with an X drawable. 'attachment' describes the
attachment point for the buffer, 'name' is the name of the
underlying kernel buffer,
â â â â â â
6. Extension Initialization
The name of this extension is "DRI2".
ââââ
DRI2QueryVersion
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, but also new value types in the DRI2CopyRegion
request. When new values are introduced, the minor version
will be increased so the client can know which values the X
server understands from the version number.
â â â â â â
7. Extension Requests
ââââ
DRI2Connect
window: WINDOW
type: STRING
â¶
driver: STRING
device: STRING
ââââ
Returns the driver name and device file to use for the
specified driver type for the screen associated with 'window'.
'type' identifies the type of driver to query for.
'driver' is the name of the driver to load. The client is
assumed to know where to look for the drivers and what to do
with it.
'device' is the filename of the DRM device file.
If the client is not local, or the request driver type is
unknown or not available, 'driver' and 'device' will be empty
strings, 'group' will be '0'. We are not using an regular X
error here to indicate failure, which will allow the client
fall back to other options more easily.
ISSUE: We could add the list of supported attachments and the
supported DRI2CopyRegion values here (just the bitmask of all
supported values).
ââââ
DRI2Authenticate
window: WINDOW
token: CARD32
ââââ
Errors: Window, Authenticate
Request that the X server authenticates 'token', allowing the
client to access the DRM buffers created by the X server on
the screen associated with 'window'.
Authentication shouldn't fail at this point, except if an
invalid token is passed, in which case an Authenticate error
is generated.
ââââ
DRI2GetBuffers
drawable: DRAWABLE
attachments: LISTofDRI2ATTACHMENTS
â¶
width, height: CARD32
buffers: LISTofDRI2BUFFER
ââââ
Errors: Window
Get buffers for the provided attachment points for the given
drawable.
If the DDX driver does not support one or more of the
specified attachment points, a Value error is generated, with
the first unsupported attachment point as the error value.
'width' and 'height' describes the dimensions of the drawable.
'buffers' is a list of DRI2BUFFER for the given DRI2
attachment points.
ââââ
DRI2CopyRegion
drawable: DRAWABLE
region: REGION
source: DRI2ATTACHMENT
destination: DRI2ATTACHMENT
value-mask: CARD32
value-list: LISTofVALUE
ââââ
Errors: Window, Value
Schedule a copy from one DRI2 buffer to another.
The value-mask and value-list specify optional attributes of
the copy operation. The possible values are:
Attribute Value
DRI2RelativeSync frame count
DRI2AbsoluteSync frame number
DRI2PreserveSource bool
DRI2RescheduleLost bool
DRI2RelativeSync and DRI2AbsoluteSync lets the client request
that the copy should be synchronized to vertical retrace in
order to avoid tearing and flicker in the update.
DRI2RelativeSync lets the client specify that the copy should
take place a number of frames after the current frame. If 0
is passed, the semantics is to schedule the copy as soon as
possible, but synchronized to vertical retrace.
DRI2AbsoluteSync lets the client specify an absolute frame
where the swap should take place. The client is expected to
query the kernel rendering manager for the current frame count
in order to compute the desired target frame. If no value is
given for either of DRI2RelativeSync or DRI2AbsoluteSync, the
behavior falls back to unspecified; in particular, an
implementation may still choose to synchronize the copy to
vertical refresh even if no specific synchronization behaviour
is requested.
If DRI2PreserveSource is not given or False, the source buffer
contents is undefined after the copy is scheduled. This lets
the X server implement DRI2CopyRegion by swapping the
underlying buffers rather than copying the contents. Setting
DRI2PreserveSource to True will leave the contents of the
source buffer unchanged. This is useful for implementing
extensions that implement copy semantics, such as
GLX_MESA_copy_sub_buffer.
Setting DRI2RescheduleLost to True requests that the server
reschedules a lost copy for the next vertical retrace.
Setting this to False will make the X server just drop any
copy requests that miss their target frame.
ISSUE: Do we really want all this? Maybe we should punt all
this to a later version of the spec when we actually sit down
and implement it. For the first iteration, I think the
DRI2PreserveSource value is sufficient. The documentation
above demonstrates how to add this in a revision of the spec.
â â â â â â
8. Extension Versioning
The DRI2 extension has undergone a number of revisions before
1.0: Released, but never used. Relied on a number of
constructs from the XF86DRI extension, such as a
shared memory area (SAREA) to communicate changes in
cliprects and window sizes, and
1.99.1: Move the swap buffer functionality into the X server,
introduce SwapBuffer request to copy back buffer
contents to the X drawable.
1.99.2: Rethink the SwapBuffer request as an asynchronous
request to copy a region between DRI2 buffers. Drop
CreateDrawable and DestroyDrawable, update Connect to
support different driver types and to send the
authentication group.
2.0: Awesomeness!
Compatibility up to 2.0 is not preserved, but was also never released.
â â â â â â
10. Relationship with other extensions
As an extension designed to support other extensions, there is
naturally some interactions with other extensions.
10.1 GLX
The GL auxilary buffers map directly to the DRI2 buffers... eh
10.2 DBE
The DBE back buffer must correspond to the DRI2_BUFFER_FRONT_LEFT
DRI2 buffer for servers that support both DBE and DRI2.
10.3 XvMC / Xv
We might add a DRI2_BUFFER_YUV to do vsynced colorspace conversion
blits. Maybe... not really sure.
â â â â â â
Appendix A. Protocol Encoding
Syntactic Conventions
This document uses the same syntactic conventions as the core X
protocol encoding document.
A.1 Common Types
ââââ
DRI2ATTACHMENT
0x0 DRI2_BUFFER_FRONT_LEFT
0x1 DRI2_BUFFER_BACK_LEFT
0x2 DRI2_BUFFER_FRONT_RIGHT
0x3 DRI2_BUFFER_BACK_RIGHT
0x4 DRI2_BUFFER_DEPTH
0x5 DRI2_BUFFER_STENCIL
0x6 DRI2_BUFFER_ACCUM
0x7 DRI2_BUFFER_FAKE_FRONT_LEFT
0x8 DRI2_BUFFER_FAKE_FRONT_RIGHT_LEFT
ââââ
Used to encode the possible attachment points.
ââââ
DRI2BUFFER
4 CARD32 attachment
4 CARD32 name
4 CARD32 pitch
4 CARD32 cpp
4 CARD32 flags
ââââ
A DRI2 buffer specifies the attachment, the kernel memory
manager name, the pitch and chars per pixel for a buffer
attached to a given drawable.
A.2 Protocol Requests
ââââ
DRI2QueryVersion
1 CARD8 major opcode
1 0 DRI2 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
ââââ
ââââ
DRI2Connect
1 CARD8 major opcode
1 1 DRI2 opcode
2 3+(n+p)/4 length
4 WINDOW window
4 CARD32 driver type name length
n CARD8 driver type name
p unused, p=pad(n)
â¶
1 1 Reply
1 unused
2 CARD16 sequence number
4 (n+m+p)/4 reply length
4 n driver name length
4 m device name length
16 unused
n CARD8 driver name
m CARD8 device name
p unused, p=pad(n+m)
ââââ
ââââ
DRI2Authenticate
1 CARD8 major opcode
1 2 DRI2 opcode
2 3 length
4 WINDOW window
4 CARD32 authentication token
ââââ
ââââ
DRI2GetBuffers
1 CARD8 major opcode
1 3 DRI2 opcode
2 3 length
4 DRAWABLE drawable
4 n number of attachments
4n LISTofDRI2ATTACHMENTS attachments
â¶
4 CARD32 width of drawable
4 CARD32 height of drawable
5n LISTofDRI2BUFFER buffers
ââââ
ââââ
DRI2CopyRegion
1 CARD8 major opcode
1 4 DRI2 opcode
2 3 length
4 DRAWABLE drawable
4 REGION region
4 DRI2ATTACHMENT source
4 DRI2ATTACHMENT destination
4 BITMASK value-mask (has n bits set to 1)
0x00000001 DRI2RelativeSync frame count
0x00000002 DRI2AbsoluteSync frame number
0x00000004 DRI2PreserveSource none
0x00000008 DRI2RescheduleLost drop/next
4n LISTofVALUE value-list
ââââ
With BITMASK and LISTofVALUE defined as in the X11 protocol
encoding document. Specifically, the most significant bit of
value-mask is reserved to allow for chained bitmasks. The
size of the individual values are 4 bytes.
VALUEs
4 CARD32 DRI2RelativeSync
4 CARD32 DRI2AbsoluteSync
4 BOOL DRI2PreserveSource
4 BOOL DRI2RescheduleLost
A.3 Protocol Events
The DRI2 extension specifies no events.
ISSUE: Maybe it should - we could introduce an event to indicate that
the copy took place and the actual frame number it hit. We can also
add that later.
A.4 Protocol Errors
ââââ
ERRORS
Base + 0 Authenticate
ââââ
â â â â â â
Appendix B. Implementation on GEM
Where to begin...
_______________________________________________
xorg mailing list
[email protected]
http://lists.freedesktop.org/mailman/listinfo/xorg
