DRI Extension for supporting Direct Rendering Protocol Specification $Date: 1999/05/11 22:45:24 $, $Revision: 1.9 $ Jens Owen (jens@precisioninsight.com) Kevin Martin (kevin@precisioninsight.com) Copyright 1999 by Precision Insight, Inc., Cedar Park, Texas. All Rights Reserved. Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are preserved on all copies. The X server and direct rendering clients require a communication protocol to communicate information not included in SAREA. This is separate from the standard GLX protocol. The protocol defines the following requests and events. Requests for DRI Specific Commands ---------------------------------- 0. Query Extension Version Name: XF86DRIQueryVersion Reply: DRI_major_version: CARD32 DRI_minor_version: CARD32 DRI_patch_version: CARD32 Errors: None Description: DRI_major_version and DRI_minor_version indicates the version of the protocol the server supports. DRI_patch_version indicates the patch level. Encoding: XF86DRIQueryVersion 1 CARD8 opcode (X assigned) 1 0 DRI opcode 2 1 request length => 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 2 CARD16 DRI_major_version 2 CARD16 DRI_minor_version 4 CARD32 DRI_minor_patch 16 unused 1. Query Direct Rendering Capable Name: XF86DRIQueryDirectRenderingCapable Request: screen: CARD32 Reply: is_capable: CARD32 Errors: BadValue Description: This request sets is_capable as True if a given screen is capable of supportint Direct Rendering, otherwise is_capable is set to False. If screen does not exist, a BadValue error is generated. Encoding: XF86DRIQueryDirectRenderingCapable 1 CARD8 opcode (X assigned) 1 1 DRI opcode 2 2 request length 4 CARD32 screen => 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 1 BOOL is_capable 23 unused 2. Open Direct Rendering Connection Name: XF86DRIOpenConnection Request: screen: CARD32 Reply: drm_client_key_low: CARD32 drm_client_key_high: CARD32 SAREA_handle_low: CARD32 SAREA_handle_high: CARD32 bus_id_string_length: CARD32 bus_id_string: STRING8 Errors: BadValue Description: This request provides the client with the drm_client_key and bus_id_string necessary to open the kernel device driver for the video card. SAREA_handle is used to map the SAREA after the kernel driver is open. The SAREA contains only device independent information. Device specific information can be passed via the XF86DRIGetDeviceInfo protocol request, which in turn can be used to create device specific shared memory segments. If screen does not exist, a BadValue error is generated. Encoding: XF86DRIOpenConnection 1 CARD8 opcode (X assigned) 1 2 DRI opcode 2 4 request length 4 CARD32 screen => 1 1 Reply 1 unused 2 CARD16 sequence number 4 (n+p)/4 reply length 4 CARD32 drm_client_key_low 4 CARD32 drm_client_key_high 4 CARD32 SAREA_handle_low 4 CARD32 SAREA_handle_high 4 CARD32 n 12 unused n STRING8 bus_id_string p unused, p=pad(n) 3. Close Direct Rendering Connection Name: XF86DRICloseConnection Request: screen: CARD32 Errors: BadValue Description: This request closes the direct rendering communication with screen and frees associated resources. If screen does not exist, a BadValue error is generated. Encoding: XF86DRICloseConnection 1 CARD8 opcode (X assigned) 1 3 DRI opcode 2 2 request length 4 CARD32 screen 4. Get Client Driver Name Name: XF86DRIGetClientDriverName Request: screen: CARD32 Reply: client_driver_major_version: CARD32 client_driver_minor_version: CARD32 client_driver_patch_version: CARD32 client_driver_name_length: CARD32 client_driver_name: STRING8 Errors: BadValue Description: This request returns the client_driver_name which is the core rendering driver module to be used when direct rendering on screen. The client driver is required to match the same major revision number as the ddx driver. The client driver minor revision is required to be greater or equal to the ddx minor revision number. The ddx patch revision is informative only. If screen does not exist, a BadValue error is generated. Encoding: XF86DRIGetClientDriverName 1 CARD8 opcode (X assigned) 1 4 DRI opcode 2 2 request length 4 CARD32 screen => 1 1 Reply 1 unused 2 CARD16 sequence number 4 (n+p)/4 reply length 4 CARD32 client_driver_major_version 4 CARD32 client_driver_minor_version 4 CARD32 client_driver_patch_version 4 CARD32 n 8 unused n STRING8 client_driver_name p unused, p=pad(n) 5. Create Direct Rendering Hardware Context Name: XF86DRICreateContext Request: visual: CARD32 screen: CARD32 context: CARD32 Reply: hw_context_handle: CARD32 Errors: BadValue, BadAlloc Description: This request creates a direct rendering hardware context for screen of visual type with context as an id. hw_context_handle is used by the direct rendering infrastructure to track this device specific hardware context. If screen does not exist, a BadValue error is generated. If the X Server does not have enough resources to allocate a new context then BadAlloc is generated. Encoding: XF86DRICreateContext 1 CARD8 opcode (X assigned) 1 5 DRI opcode 2 3 request length 4 CARD32 visual 4 CARD32 screen 4 CARD32 context => 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 CARD32 hw_context_handle 20 unused 6. Destroy Direct Rendering Context Name: XF86DRIDestroyContext Request: screen: CARD32 context: CARD32 Errors: BadValue Description: This request destroys the direct rendering hardware context associated with context on screen. If hw_context_handle does not exist, a BadValue error is generated. Encoding: XF86DRIDestroyContext 1 CARD8 opcode (X assigned) 1 6 DRI opcode 2 3 request length 4 CARD32 screen 4 CARD32 context 7. Create Direct Rendering Drawable Name: XF86DRICreateDrawable Request: screen: CARD32 drawable: CARD32 Reply: hw_drawable_handle: CARD32 Errors: BadValue, BadAlloc Description: This request creates a direct rendering drawable for screen that is directly associated with the X Server's drawable. hw_drawable_handle is used by the direct rendering infrastructure to track this direct rendering drawable. If screen or drawable does not exist, a BadValue error is generated. If the X Server does not have enough resources to allocate a new direct rendering drawable then BadAlloc is generated. Encoding: XF86DRICreateDrawable 1 CARD8 opcode (X assigned) 1 7 DRI opcode 2 3 request length 4 CARD32 screen 4 CARD32 drawable => 1 1 Reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 CARD32 hw_drawable_handle 20 unused 8. Destroy Direct Rendering Drawable Name: XF86DRIDestroyDrawable Request: screen: CARD32 drawable: CARD32 Errors: BadValue Description: This request destroys the direct rendering drawable associated with drawable on screen. If drawable does not exist, or does not have an associated direct rendering drawable, then a BadValue error is generated. Encoding: XF86DRIDestroyDrawable 1 CARD8 opcode (X assigned) 1 8 DRI opcode 2 3 request length 4 CARD32 screen 4 CARD32 drawable 9. Get Direct Rendering Drawable Information Name: XF86DRIGetDrawableInfo Request: screen: CARD32 drawable: CARD32 Reply: drawable_table_index: CARD32 drawable_table_stamp: CARD32 drawable_origin_X: INT16 drawable_origin_Y: INT16 drawable_size_W: INT16 drawable_size_H: INT16 num_clip_rects: CARD32 clip_rects: DRICLIPRECT Errors: BadValue Description: The request returns drawable region information for the direct rendering drawable associated with drawable. Region information is returned in the form of drawable_origin, drawable_size and clip_rects. drawable_table_index is an offset into the drawable table in the SAREA for screen, whose context will match drawable_table_stamp as long as the drawable information is valid. If screen or drawable does not exist, or an associated direct rendering drawable does not exist, then a BadValue error is generated. Encoding: XF86DRIGetDrawableInfo 1 CARD8 opcode (X assigned) 1 9 DRI opcode 2 3 request length 4 CARD32 screen 4 CARD32 drawable => 1 1 Reply 1 unused 2 CARD16 sequence number 4 n*4 reply length 4 CARD32 drawable_table_index 4 CARD32 drawable_table_stamp 2 INT16 drawable_origin_X 2 INT16 drawable_origin_Y 2 INT16 drawable_size_W 2 INT16 drawable_size_H 4 CARD32 num_clip_rects (n) 4 unused n DRICLIPRECT clip_rects 10. Get Device Information Name: XF86DRIGetDeviceInfo Request: screen: CARD32 Reply: framebuffer_handle_low: CARD32 framebuffer_handle_high: CARD32 framebuffer_origin_offset: CARD32 framebuffer_size: CARD32 framebuffer_stride: CARD32 device_private_size: CARD32 device_private: CARD32 Errors: BadValue Description: The request returns device information for screen. framebuffer information and other device specific information are conveyed. If screen does not exist, a BadValue error is generated. Encoding: XF86DRIGetDeviceInfo 1 CARD8 opcode (X assigned) 1 10 DRI opcode 2 2 request length 4 CARD32 screen => 1 1 Reply 1 unused 2 CARD16 sequence number 4 n*4 reply length 4 CARD32 framebuffer_handle_low 4 CARD32 framebuffer_handle_high 4 CARD32 framebuffer_origin_offset 4 CARD32 framebuffer_size 4 CARD32 framebuffer_stride 4 CARD32 device_private_size (n) n CARD32 device_private