[PATCH] RandR version 1.4 additions
Aaron Plattner
aplattner at nvidia.com
Mon Dec 6 09:20:29 PST 2010
On Sun, Dec 05, 2010 at 08:43:07PM -0800, Keith Packard wrote:
> On Sun, 5 Dec 2010 16:38:52 -0800, Aaron Plattner <aplattner at nvidia.com> wrote:
>
> This adds the specification and protocol header definitions for the
> RandR 1.4 protocol changes, including
>
> * Per crtc pixmaps and pixmap origins
> * Sprite position and image transforms
> * SetCrtcConfigs request
>
> Signed-off-by: Keith Packard <keithp at keithp.com>
>
> ---
>
> > There are a few whitespace bugs, such as this:
>
> I've sent a patch cleaning up the whitespace before the 1.4 additions to
> the xorg-devel list and fixed the whitespace in my new additions.
>
> And, I've tried to clarify the arguments inside the CRTCCONFIG
> structure.
>
> Here's the complete patch, without the whitespace cleanups. Oh, it's
> missing the encoding section in randrproto.txt; I'll add that later.
>
> configure.ac | 2 +-
> randr.h | 14 +++++-
> randrproto.h | 119 +++++++++++++++++++++++++++++++++++++++++++++
> randrproto.txt | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
> 4 files changed, 278 insertions(+), 4 deletions(-)
>
> diff --git a/configure.ac b/configure.ac
> index 5cfa3ec..527618d 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -22,7 +22,7 @@ dnl
> dnl Process this file with autoconf to create configure.
>
> AC_PREREQ([2.57])
> -AC_INIT([RandrProto], [1.3.1], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
> +AC_INIT([RandrProto], [1.4.0], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
> AM_INIT_AUTOMAKE([foreign dist-bzip2])
>
> # Require xorg-macros: XORG_CHANGELOG
> diff --git a/randr.h b/randr.h
> index 1ee95f9..4480f5c 100644
> --- a/randr.h
> +++ b/randr.h
> @@ -40,11 +40,11 @@ typedef unsigned long XRandrModeFlags;
>
> #define RANDR_NAME "RANDR"
> #define RANDR_MAJOR 1
> -#define RANDR_MINOR 3
> +#define RANDR_MINOR 4
>
> #define RRNumberErrors 3
> #define RRNumberEvents 2
> -#define RRNumberRequests 32
> +#define RRNumberRequests 37
>
> #define X_RRQueryVersion 0
> /* we skip 1 to make old clients fail pretty immediately */
> @@ -92,6 +92,13 @@ typedef unsigned long XRandrModeFlags;
> #define RRTransformScaleDown (1L << 2)
> #define RRTransformProjective (1L << 3)
>
> +/* V1.4 additions */
> +#define X_RRQueryScanoutPixmaps 32
> +#define X_RRCreateScanoutPixmap 33
> +#define X_RRSetCrtcSpriteTransform 34
> +#define X_RRGetCrtcSpriteTransform 35
> +#define X_RRSetCrtcConfigs 36
> +
> /* Event selection bits */
> #define RRScreenChangeNotifyMask (1L << 0)
> /* V1.2 additions */
> @@ -149,6 +156,9 @@ typedef unsigned long XRandrModeFlags;
> #define BadRRCrtc 1
> #define BadRRMode 2
>
> +/* new in 1.4 protocol */
> +#define RR_CurrentScanoutPixmap 1 /* current scanout pixmap in RRSetCrtcConfigs */
> +
> /* Conventional RandR output properties */
>
> #define RR_PROPERTY_BACKLIGHT "Backlight"
> diff --git a/randrproto.h b/randrproto.h
> index 3b98a9f..54abafc 100644
> --- a/randrproto.h
> +++ b/randrproto.h
> @@ -49,6 +49,7 @@
> #define RRMode CARD32
> #define RRCrtc CARD32
> #define RRModeFlags CARD32
> +#define PictFormat CARD32
I don't see a corresponding #undef PictFormat.
> #define Rotation CARD16
> #define SizeID CARD16
> @@ -646,6 +647,124 @@ typedef struct {
> #define sz_xRRGetOutputPrimaryReply 32
>
> /*
> + * Additions for 1.4
> + */
> +
> +typedef struct {
> + PictFormat format B32;
> + CARD16 maxWidth B16, maxHeight B16;
> + Rotation rotations B16;
> + CARD16 pad0 B16;
> + CARD32 pad1 B32;
> +} xRRScanoutPixmapInfo;
> +#define sz_xRRScanoutPixmapInfo 16
> +
> +typedef struct {
> + RRCrtc crtc B32;
> + INT16 x B16, y B16;
> + RRMode mode B32;
> + Rotation rotation B16;
> + CARD16 nOutput B16;
> + xRenderTransform spritePositionTransform;
> + xRenderTransform spriteImageTransform;
> + Pixmap pixmap B32;
> + INT16 xPixmap B16, yPixmap B16;
> +} xRRCrtcConfig;
> +#define sz_xRRCrtcConfig (2*sz_xRenderTransform + 24)
> +
> +typedef struct {
> + CARD8 reqType;
> + CARD8 randrReqType;
> + CARD16 length B16;
> + Drawable drawable B32;
> +} xRRQueryScanoutPixmapsReq;
> +#define sz_xRRQueryScanoutPixmapsReq 8
> +
> +typedef struct {
> + BYTE type;
> + CARD8 pad;
> + CARD16 sequenceNumber B16;
> + CARD32 length B32;
> + CARD32 pad0 B32;
> + CARD32 pad1 B32;
> + CARD32 pad2 B32;
> + CARD32 pad3 B32;
> + CARD32 pad4 B32;
> + CARD32 pad5 B32;
> +} xRRQueryScanoutPixmapsReply;
> +#define sz_xRRQueryScanoutPixmapsReply 32
> +
> +typedef struct {
> + CARD8 reqType;
> + CARD8 randrReqType;
> + CARD16 length B16;
> + Pixmap pid B32;
> + Drawable drawable B32;
> + CARD16 width B16, height B16;
> + PictFormat format B32;
> + Rotation rotations B16;
> + CARD16 pad B16;
> +} xRRCreateScanoutPixmapReq;
> +#define sz_xRRCreateScanoutPixmapReq 24
> +
> +typedef struct {
> + CARD8 reqType;
> + CARD8 randrReqType;
> + CARD16 length B16;
> + RRCrtc crtc B32;
> + xRenderTransform positionTransform;
> + xRenderTransform imageTransform;
> +} xRRSetCrtcSpriteTransformReq;
> +#define sz_xRRSetCrtcSpriteTransformReq (2*sz_xRenderTransform + 8)
> +
> +typedef struct {
> + CARD8 reqType;
> + CARD8 randrReqType;
> + CARD16 length B16;
> + RRCrtc crtc B32;
> +} xRRGetCrtcSpriteTransformReq;
> +#define sz_xRRGetCrtcSpriteTransformReq 8
> +
> +typedef struct {
> + BYTE type;
> + CARD8 pad;
> + CARD16 sequenceNumber B16;
> + CARD32 length B32;
> + xRenderTransform positionTransform;
> + xRenderTransform imageTransform;
> +} xRRGetCrtcSpriteTransformReply;
> +#define sz_xRRGetCrtcSpriteTransformReply (2*sz_xRenderTransform + 8)
> +
> +typedef struct {
> + CARD8 reqType;
> + CARD8 randrReqType;
> + CARD16 length B16;
> + Drawable drawable B32;
> + CARD16 screenPixmapWidth B16, screenPixmapHeight B16;
> + CARD16 screenWidth B16, screenHeight B16;
> + CARD32 widthInMillimeters B32;
> + CARD32 heightInMillimeters B32;
> + CARD16 nConfigs B16;
> + CARD16 pad0 B16;
> + CARD32 pad1 B32;
> +} xRRSetCrtcConfigsReq;
> +#define sz_xRRSetCrtcConfigsReq 32
> +
> +typedef struct {
> + BYTE type;
> + CARD8 status;
> + CARD16 sequenceNumber B16;
> + CARD32 length B32;
> + CARD32 pad0 B32;
> + CARD32 pad1 B32;
> + CARD32 pad2 B16;
> + CARD32 pad3 B32;
> + CARD32 pad4 B32;
> + CARD32 pad5 B32;
> +} xRRSetCrtcConfigsReply;
> +#define sz_xRRSetCrtcConfigsReply 32
> +
> +/*
> * event
> */
> typedef struct {
These all seem okay.
> diff --git a/randrproto.txt b/randrproto.txt
> index 9f3d4a1..0d537ac 100644
> --- a/randrproto.txt
> +++ b/randrproto.txt
> @@ -124,7 +124,23 @@ following features are added in this version:
> • Panning. It was removed with RandR 1.2 because the old semantics didn't
> fit any longer. With RandR 1.3 panning can be specified per crtc.
>
> -1.1 Acknowledgements
> +1.4 Introduction to version 1.4 of the extension
> +
> +Version 1.4 adds a couple more capabilities to further expose the
> +underlying hardware to clients
> +
> + • Per-crtc pixmaps. This provides for multiple scan-out buffers
> + which applications can create and assign to arbitrary collections
> + of crtcs. These pixmaps can be associated with a window for use
> + with OpenGL or drawn to directly.
This still causes pangs of worry that it's going to cause some weird
interaction problem down the road with features like stereo or overlays or
whatever, but I think that as long as we treat windows that are not the
magic scanout window as being redirected, and the magic scanout window as
being unoccluded and full-screen, then it all works out.
I wonder if this'll be useful for games as the full-screen exclusive mode
that's been so sorely missed.
> + • RRSetCrtcConfigs request. This supplies a set of
> + crtc configurations to the server that must be applied together
> + or not at all. This can reduce screen flicker while also
> + providing the server a complete configuration for appropriate
> + resource management.
> +
> +1.99 Acknowledgements
>
> Our thanks to the contributors to the design found on the xpert mailing
> list, in particular:
> @@ -302,6 +318,49 @@ REFRESH { rates: LISTofCARD16 }
>
> ❧❧❧❧❧❧❧❧❧❧❧
>
> +5.4. Protocol Types added in version 1.4 of the extension
> +
> +SCANOUTPIXMAPINFO { format: PICTFORMAT
> + maxWidth, maxHeight: CARD16
> + rotations: SETofROTATION }
> +
> +CRTCCONFIG { crtc: CRTC
> + x, y: INT16
> + mode: MODE
> + rotation: ROTATION
> + sprite-position-transform: TRANSFORM
> + sprite-image-transform: TRANSFORM
> + outputs: LISTofOUTPUT
> + pixmap: PIXMAP, None or CurrenScanoutPixmap
s/Curren/Current/
> + pixmap-x, pixmap-y: INT16 }
> +
> + The sprite-position-transform and sprite-image-transform
> + values are used as in the RRSetCrtcSpriteTransform request
> + position-transform and image-transform parameters.
> +
> + 'pixmap' specifies the origin of the pixel data to be presented on
> + 'crtc'. If 'pixmap' is None, then data will be presented from
> + the screen pixmap. If 'pixmap' is 'CurrentScanoutPixmap', then
> + whatever source is current in use will remain in use, whether
s/current/currently/
> + that is the screen pixmap or some other allocated scanout pixmap.
> +
> + 'pixmap-x' and 'pixmap-y' specify the origin of the scanout
> + data within the pixmap, the area from that location to
> + pixmap-x + width-of(mode), pixmap-y + height-of(mode) is what
> + will be seen on the connected outputs.
Thank you.
> + The pixmap value must specify a scanout pixmap as created by
> + RRCreateScanoutPixmap, or a Match error results.
> +
> + The specified pixmap must be at least as large as the area to
> + be scanned out, or a Match error results.
> +
> + The specified pixmap must have had the specified 'rotation'
> + included as a part of its creation paramaeters, or a Match
> + error results.
> +
> + ❧❧❧❧❧❧❧❧❧❧❧
> +
> 6. Extension Initialization
>
> The name of this extension is "RANDR".
> @@ -1238,6 +1297,92 @@ dynamic changes in the display environment.
>
> ❧❧❧❧❧❧❧❧❧❧❧
>
> +7.3. Extension Requests added in version 1.4 of the extension.
> +
> +┌───
> + RRQueryScanoutPixmaps
> + window: WINDOW
> + ▶
> + infos: LISTofSCANOUTPIXMAPINFO
> +└───
> + Errors: Window
> +
> + This request returns information about the server support for
> + alternate scanout pixmaps. For each pictformat, there is a set
> + of rotations and a maximum supported size. The rotations here
> + are those provided by the scanout hardware itself, not by
> + software emulation.
Can this include indexed formats? Should there be some provision for
specifying a colormap along with the pixmap to assign the pixel-to-color
transfer function, or is the gamma ramp interface sufficient?
If somebody wants to use this for full-screen exclusive games, they'll
probably want to install the game's colormap on that crtc and have colormap
changes from the application apply to the CLUT hardware like they do for
normal windows today.
> +┌───
> + RRCreateScanoutPixmap
> + pixmap: PIXMAP
> + drawable: DRAWABLE
> + width, height: CARD16
> + format: PICTFORMAT
> + rotations: SETofROTATION
> +└───
> + Errors: Drawable, Match, Value
> +
> + Creates a pixmap which can subsequently be used as a scanout
> + buffer for the screen associated with 'drawable'. 'rotations'
> + is the set of rotation values which may be used with the
> + resulting scanout buffer when it is associated with a CRTC.
> +
> + 'format' must be one of the supported scanout formats, or a
> + Match error results.
> +
> + 'width' and 'height' must be within the supported range for
> + the specified format or a Value error results.
> +
> + 'rotations' must be a subset of those supported for the
> + specified format or a Match error results.
> +
> +┌───
> + RRSetCrtcSpriteTransform
> + crtc: CRTC
> + position-transform: TRANSFORM
> + image-transform: TRANSFORM
> +└───
> + Sets the sprite transforms for the specified crtc, any sprites
> + presented on this crtc will have their positions transformed
> + by the position-transform matrix. Sprite images displayed on the crtc
> + will be transformed by the image-transform matrix.
> +
> +┌───
> + RRGetCrtcSpriteTransform
> + crtc: CRTC
> + ▶
> + position-transform: TRANSFORM
> + image-transform: TRANSFORM
> +└───
> + Gets the sprite transforms for the specified crtc.
> +
> +┌───
> + RRSetCrtcConfigs
> + drawable: DRAWABLE
> + screen-pixmap-width: CARD16
> + screen-pixmap-height: CARD16
> + screen-width: CARD16
> + screen-height: CARD16
> + width-in-millimeters: CARD32
> + height-in-millimeters: CARD32
> + configs: LISTofCRTCCONFIG
> + ▶
> + status: RRCONFIGSTATUS
> +└───
> + Errors: Value, Match
> +
> + This works much like RRSetScreenSize followed by a sequence of
> + RRSetCrtcConfig, except that the entire configuration is set
> + in a single operation, either succeeding or failing without
> + any partial execution.
> +
> + In addition to the pre-1.4 semantics, this request adds the
> + ability to specific a scanout pixmap for each crtc, and
> + integrates the 1.4 sprite transform request as well.
> +
> + ❧❧❧❧❧❧❧❧❧❧❧
> +
> 8. Extension Events
>
> Clients MAY select for ConfigureNotify on the root window to be
> --
> 1.7.2.3
Aside from the minor spelling issues, the missing #undef PictFormat, and
the colormap question above,
Reviewed-by: Aaron Plattner <aplattner at nvidia.com>
More information about the xorg-devel
mailing list