12 The DRI2 extension is designed to associate and access auxillary
13 rendering buffers with an X drawable.
15 DRI2 is a essentially a helper extension to support implementation of
16 direct rendering drivers/libraries/technologies.
18 The main consumer of this extension will be a direct rendering OpenGL
19 driver, but the DRI2 extension is not designed to be OpenGL specific.
20 Direct rendering implementations of OpenVG, Xv, cairo and other
21 graphics APIs should find the functionality exposed by this extension
22 helpful and hopefully sufficient.
29 Kevin E. Martin <kem@redhat.com>
30 Keith Packard <keithp@keithp.com>
31 Eric Anholt <eric@anholt.net>
32 Keith Whitwell <keith@tungstengraphics.com>
33 Jerome Glisse <glisse@freedesktop.org>
34 Ian Romanick <ian.d.romanick@intel.com>
35 Michel Dänzer <michel@tungstengraphics.com>
36 Jesse Barnes <jbarnes@virtuousgeek.org>
45 2.1. Attachment points
47 Stolen from OpenGL FBOs, I guess.
50 2.2. Kernel rendering manager
52 This specification assumes a rendering architechture, where an
53 underlying kernel rendering manager that can provide 32 bit integer
54 handles to video memory buffers. These handles can be passed between
55 processes, which, through a direct rendering driver, submit rendering
56 to the kernel rendering manager, targeting and/or sourcing from these
57 buffers. This extension provides a means to communicate about such
58 buffers as associated with an X drawable.
60 The details of how the a direct rendering driver use the buffer names
61 and submit the rendering requests is outside the scope of this
62 specification. However, Appendix B does discuss implementation of
63 this specification on the Graphics Execution Manager (GEM).
68 No ordering between swap buffers and X rendering. X rendering to src
69 buffers will block if they have a vblank pending.
72 2.4 Authentication model
74 The purpose of the DRM authentication scheme is to grant access to the
75 kernel rendering manager buffers created by the X server if, and only
76 if, the client has access to the X server. This is achieved in a
79 1) The client gets a token from the kernel rendering manager
80 that uniquely identifies it. The token is a 32 bit integer.
82 2) The client passes the token to the X server in the
83 DRI2Authenticate request. This request is a round trip to
84 make sure the X server has received and processed the
85 authentication before the client starts accessing the DRM.
87 3) The X server authorizes the client by passing the token to
88 the kernel rendering manager.
90 A kernel rendering manager can choose not to implement any
91 authentication and just allow access to all buffers.
94 2.5 Rendering to the X front buffer
96 OpenGL allows the client to render to the front buffer, either by
97 using a single-buffered configuration or but explicitly setting the
98 draw buffer to GL_FRONT_LEFT. Not allowed!
100 The client must ask for a fake front buffer, render to that and then
101 use DRI2CopyRegion to copy contents back and forth between the fake
102 front buffer and the real front buffer. When X and direct rendering
103 to a front buffer is interleaved, it is the responsibility of the
104 application to synchronize access using glXWaitGL and glXWaitX. A
105 DRI2 implementation of direct rendering GLX, should use these enty
106 points to copy contents back and forth to as necessary to ensure
107 consistent rendering.
109 The client may also use the DRI2SwapBuffers function to request a swap
110 of the front and back buffers. If the display server supports it, this
111 operation may be preferred, since it may be easier and/or more performant
112 for the server to perform a simple buffer swap rather than a blit.
114 2.6 Synchronizing rendering
116 DRI2 provides several methods for synchronizing drawing with various events.
117 The protocol for these methods is based on the SGI_video_sync and
118 OML_sync_control GLX extensions. Using the DRI2WaitMSC request, a client
119 can wait for a specific frame count or divisor/remainder before continuing
120 its processing. With the DRI2WaitSBC request, clients can block until a given
121 swap count is reached (as incremented by DRI2SwapBuffers). Finally, using
122 DRI2SwapBuffers, clients can limit their frame rate by specifying a swap
123 interval using the swap interval call (currently only available through GLX)
124 or by using the OML swap buffers routine.
128 DRI2 provides an event to indicate when a DRI2SwapBuffers request has
129 been completed. This can be used to throttle drawing on the client
130 side and tie into application main loops.
132 Another event is generated when the validity of the requested buffers
140 The server side region support specified in the Xfixes extension
141 version 2 is used in the CopyRegion request.
149 No errors are defined by the DRI2 extension.
156 The only events provided by DRI2 are DRI2_BufferSwapComplete
157 and DRI2InvalidateBuffers.
165 DRI2DRIVER { DRI2DriverDRI
168 These values describe the type of driver the client will want
169 to load. The server sends back the name of the driver to use
170 for the screen in question.
172 DRI2ATTACHMENT { DRI2BufferFrontLeft
179 DRI2BufferFakeFrontLeft
180 DRI2BufferFakeFrontRight
181 DRI2BufferDepthStencil
184 These values describe various attachment points for DRI2
187 DRI2BUFFER { attachment: CARD32
193 The DRI2BUFFER describes an auxillary rendering buffer
194 associated with an X drawable. 'attachment' describes the
195 attachment point for the buffer, 'name' is the name of the
196 underlying kernel buffer,
199 DRI2ATTACH_FORMAT { attachment: CARD32
202 The DRI2ATTACH_FORMAT describes an attachment and the associated
203 format. 'attachment' describes the attachment point for the buffer,
204 'format' describes an opaque, device-dependent format for the buffer.
209 7. Extension Initialization
211 The name of this extension is "DRI2".
215 client-major-version: CARD32
216 client-minor-version: CARD32
218 major-version: CARD32
219 minor-version: CARD32
222 The client sends the highest supported version to the server
223 and the server sends the highest version it supports, but no
224 higher than the requested version. Major versions changes can
225 introduce incompatibilities in existing functionality, minor
226 version changes introduce only backward compatible changes.
227 It is the clients responsibility to ensure that the server
228 supports a version which is compatible with its expectations.
230 Backwards compatible changes included addition of new
231 requests, but also new value types in the DRI2CopyRegion
232 request. When new values are introduced, the minor version
233 will be increased so the client can know which values the X
234 server understands from the version number.
240 8. Extension Requests
245 driverType: DRI2DRIVER
251 Returns the driver name and device file to use for the
252 specified driver type for the screen associated with 'window'.
254 'type' identifies the type of driver to query for.
256 'driver' is the name of the driver to load. The client is
257 assumed to know where to look for the drivers and what to do
260 'device' is the filename of the DRM device file.
262 If the client is not local, or the request driver type is
263 unknown or not available, 'driver' and 'device' will be empty
264 strings. We are not using an regular X
265 error here to indicate failure, which will allow the client
266 fall back to other options more easily.
268 ISSUE: We could add the list of supported attachments and the
269 supported DRI2CopyRegion values here (just the bitmask of all
277 authenticated: CARD32
281 Request that the X server authenticates 'token', allowing the
282 client to access the DRM buffers created by the X server on
283 the screen associated with 'window'.
285 Authentication shouldn't fail at this point, except if an
286 invalid token is passed, in which case authenticated is False.
291 attachments: LISTofDRI2ATTACHMENTS
293 width, height: CARD32
294 buffers: LISTofDRI2BUFFER
298 Get buffers for the provided attachment points for the given
301 If the DDX driver does not support one or more of the
302 specified attachment points, a Value error is generated, with
303 the first unsupported attachment point as the error value.
305 'width' and 'height' describes the dimensions of the drawable.
307 'buffers' is a list of DRI2BUFFER for the given DRI2
314 source: DRI2ATTACHMENT
315 destination: DRI2ATTACHMENT
318 Errors: Window, Value
320 Schedule a copy from one DRI2 buffer to another.
322 The DRICopyRegion request has a reply but it is empty. The
323 reply is there to let the direct rendering client wait until
324 the server has seen the request before proceeding with
325 rendering the next frame.
335 Schedule a swap of the front and back buffers with the display
338 Returns the swap count value when the swap will actually occur (e.g.
339 the last queued swap count + (pending swap count * swap interval)).
341 This request is only available with protocol version 1.2 or
345 DRI2GetBuffersWithFormat
347 attachments: LISTofDRI2ATTACH_FORMAT
349 width, height: CARD32
350 buffers: LISTofDRI2BUFFER
354 Get buffers for the provided attachment points with the specified
355 formats for the given drawable.
357 If the DDX driver does not support one or more of the
358 specified attachment points or formats, a Value error is generated,
359 with the first unsupported attachment point as the error value.
361 'width' and 'height' describes the dimensions of the drawable.
363 'buffers' is a list of DRI2BUFFER for the given DRI2
366 This request is only available with protocol version 1.1 or
373 ust, msc, sbc: CARD64
377 Get the current media stamp counter (MSC) and swap buffer count (SBC)
378 along with the unadjusted system time (UST) when the MSC was last
381 This request is only available with protocol version 1.2 or
387 target_msc: two CARD32s
389 remainder: two CARD32s
391 ust, msc, sbc: CARD64
395 Blocks the client until either the frame count reaches target_msc or,
396 if the frame count is already greater than target_msc when the request
397 is received, until the frame count % divisor = remainder. If divisor
398 is 0, the client will be unblocked if the frame count is greater than
399 or equal to the target_msc.
401 Returns the current media stamp counter (MSC) and swap buffer count
402 (SBC) along with the unadjusted system time (UST) when the MSC was last
405 This request is only available with protocol version 1.2 or
411 target_sbc: two CARD32s
413 ust, msc, sbc: CARD64
417 Blocks the client until the swap buffer count reaches target_sbc. If
418 the swap buffer count is already greater than or equal to target_sbc
419 when the request is recieved, this request will return immediately.
421 If target_sbc is 0, this request will block the client until all
422 previous DRI2SwapBuffers requests have completed.
424 Returns the current media stamp counter (MSC) and swap buffer count
425 (SBC) along with the unadjusted system time (UST) when the MSC was last
428 This request is only available with protocol version 1.2 or
439 Sets the swap interval for DRAWABLE. This will throttle
440 DRI2SwapBuffers requests to swap at most once per interval frames,
441 which is useful useful for limiting the frame rate.
448 is_param_recognized: BOOL
453 Get the value of a parameter. The parameter's value is looked up on
454 the screen associated with 'drawable'.
456 Parameter names in which the value of the most significant byte is
457 0 are reserved for the X server. Currently, no such parameter names
458 are defined. (When any such names are defined, they will be defined in
459 this extension specification and its associated headers).
461 Parameter names in which the byte's value is 1 are reserved for the
462 DDX. Such names are private to each driver and shall be defined in the
463 respective driver's headers.
465 Parameter names in which the byte's value is neither 0 nor 1 are
466 reserved for future use.
468 Possible values of 'is_param_recognized' are true (1) and false (0).
469 If false, then 'value' is undefined.
471 This request is only available with protocol version 1.4 or later.
478 DRI2BufferSwapComplete
487 This event reports the status of the last DRI2SwapBuffers event to
488 the client. The event type should be one of DRI2_EXCHANGE_COMPLETE,
489 indicating a successful buffer exchange, DRI2_BLIT_COMPLETE, indicating
490 the swap was performed with a blit, and DRI2_FLIP_COMPLETE, indicating
491 a full page flip was completed.
494 DRI2InvalidateBuffers
499 This event is generated when the buffers the client had
500 requested for 'drawable' (with DRI2GetBuffers or
501 DRI2GetBuffersWithFormat) become inappropriate because they
502 don't match the drawable dimensions anymore, or a buffer swap
505 Note that the server is only required to warn the client once
506 about this condition, until the client takes care of bringing
507 them back up-to-date with another GetBuffers request.
511 10. Extension Versioning
513 The DRI2 extension has undergone a number of revisions before
515 1.0: Released, but never used. Relied on a number of
516 constructs from the XF86DRI extension, such as a
517 shared memory area (SAREA) to communicate changes in
518 cliprects and window sizes, and
520 1.99.1: Move the swap buffer functionality into the X server,
521 introduce SwapBuffer request to copy back buffer
522 contents to the X drawable.
524 1.99.2: Rethink the SwapBuffer request as an asynchronous
525 request to copy a region between DRI2 buffers. Drop
526 CreateDrawable and DestroyDrawable, update Connect to
527 support different driver types and to send the
528 authentication group.
530 1.99.3: Drop the bitmask argument intended to indicate
531 presence of optional arguments for CopyRegion.
535 2.1: True excellence. Added DRI2GetBuffersWithFormat to allow
536 more flexible object creation.
538 2.2: Approaching perfection. Added requests for swapbuffers,
539 MSC and SBC related requests, and events.
541 2.3: Added the DRI2InvalidateBuffers event.
543 2.6: Enlightenment attained. Added the DRI2BufferHiz attachment.
545 2.7: Added the DRI2GetParam request.
547 Compatibility up to 2.0 is not preserved, but was also never released.
553 11. Relationship with other extensions
555 As an extension designed to support other extensions, there is
556 naturally some interactions with other extensions.
561 The GL auxilary buffers map directly to the DRI2 buffers... eh
566 The DBE back buffer must correspond to the DRI2_BUFFER_FRONT_LEFT
567 DRI2 buffer for servers that support both DBE and DRI2.
572 We might add a DRI2_BUFFER_YUV to do vsynced colorspace conversion
573 blits. Maybe... not really sure.
579 Appendix A. Protocol Encoding
581 Syntactic Conventions
583 This document uses the same syntactic conventions as the core X
584 protocol encoding document.
597 0x0 DRI2BufferFrontLeft
598 0x1 DRI2BufferBackLeft
599 0x2 DRI2BufferFrontRight
600 0x3 DRI2BufferBackRight
602 0x5 DRI2BufferStencil
604 0x7 DRI2BufferFakeFrontLeft
605 0x8 DRI2BufferFakeFrontRight
606 0x9 DRI2BufferDepthStencil
609 Used to encode the possible attachment points. The attachment
610 DRI2BufferDepthStencil is only available with protocol version 1.1 or
621 A DRI2 buffer specifies the attachment, the kernel memory
622 manager name, the pitch and chars per pixel for a buffer
623 attached to a given drawable.
630 Used to describe the attachment and format requested from the server.
631 This data type is only available with protocol version 1.1 or
634 A.2 Protocol Requests
641 4 CARD32 major version
642 4 CARD32 minor version
646 2 CARD16 sequence number
648 4 CARD32 major version
649 4 CARD32 minor version
663 2 CARD16 sequence number
664 4 (n+m+p+q)/4 reply length
665 4 n driver name length
666 4 m device name length
680 4 CARD32 authentication token
684 2 CARD16 sequence number
686 4 CARD32 authenticated
696 4 n number of attachments
697 4n LISTofDRI2ATTACHMENTS attachments
701 2 CARD16 sequence number
703 4 CARD32 width of drawable
704 4 CARD32 height of drawable
705 4 CARD32 buffer count
707 5n LISTofDRI2BUFFER buffers
717 4 DRI2ATTACHMENT source
718 4 DRI2ATTACHMENT destination
722 2 CARD16 sequence number
728 DRI2GetBuffersWithFormat
733 4 n number of attachments
734 8n LISTofDRI2ATTACH_FORMAT attachments and formats
738 2 CARD16 sequence number
740 4 CARD32 width of drawable
741 4 CARD32 height of drawable
742 4 CARD32 buffer count
744 5n LISTofDRI2BUFFER buffers
756 2 CARD16 sequence number
758 4 CARD32 buffer count
765 5n LISTofDRI2BUFFER buffers
774 4 CARD32 target_msc_hi
775 4 CARD32 target_msc_lo
778 4 CARD32 remainder_hi
779 4 CARD32 remainder_lo
783 2 CARD16 sequence number
787 5n LISTofDRI2BUFFER buffers
799 2 CARD16 sequence number
815 4 CARD32 target_msc_hi
816 4 CARD32 target_msc_lo
819 4 CARD32 remainder_hi
820 4 CARD32 remainder_lo
824 2 CARD16 sequence number
845 2 CARD16 sequence number
874 1 BOOL is_param_recognized
875 2 CARD16 sequence number
884 The DRI2 extension specifies DRI2_BufferSwapComplete and
885 DRI2_InvalidateBuffers events.
888 DRI2_BufferSwapComplete
891 2 CARD16 sequenceNumber
904 DRI2_InvalidateBuffers
907 2 CARD16 sequenceNumber
919 The DRI2 extension specifies no errors.
925 Appendix B. Implementation on GEM