[RFC] DeepColor Visual Class Extension
Alex Goins
agoins at nvidia.com
Sat Oct 14 01:37:14 UTC 2017
Thanks, Adam.
Here's an updated version of the spec:
DeepColor Extension
Version X.X
2017-XX-XX
Alex Goins
agoins at nvidia.com
NVIDIA Corporation
1. Introduction
The DeepColor Extension provides a means to expose visuals suitable for use with
formats that are incompatible with the existing visuals that make use of the
core X visual classes: StaticGray, StaticColor, TrueColor, GrayScale,
PseudoColor, and DirectColor.
These visual classes as defined by the core X11 protocol are insufficient for
visuals that require a greater than 32 bit depth, or non-integer formats. As
such, they are not suitable for many HDR formats.
In order to remediate this limitation without breaking existing applications,
the DeepColor extension provides visuals that appear to the core protocol as
standard TrueColor visuals, but utilize additional requests as defined by the
DeepColor extension to determine extended properties defining the actual format
of the associated window, including pixel format and color space/encoding.
Facilities are also provided for determining the capabilities and preferences of
the compositor and displays.
Visuals exposed via this extension will hereby be referred to as "DeepColor
visuals," and their associated windows will be referred to as "DeepColor
windows."
1.1. Acknowledgements
Zach Angold, NVIDIA Corporation <zangold at nvidia.com>
Gary Demos, <garyd at alumni.caltech.edu>
Adam Jackson, Red Hat, Inc. <ajax at nwnk.net>
James Jones, NVIDIA Corporation <jajones at nvidia.com>
Robert Morell, NVIDIA Corporation <rmorell at nvidia.com>
Keith Packard, Hewlett-Packard Company <keithp at keithp.com>
Aaron Plattner, NVIDIA Corporation <aplattner at nvidia.com>
Andy Ritger, NVIDIA Corporation <aritger at nvidia.com>
1.2. External Extension Dependencies
This extension references the RandR extension for interaction with outputs
using the OUTPUT protocol type and Output error, the Composite extension for
interaction with RedirectSubwindows and UnredirectSubwindows, and the Render
extension for use of the FIXED protocol type.
Events are delivered via the Generic Event Extension.
2. DeepColor Core Protocol Behavior
DeepColor visuals appear as ordinary TrueColor visuals to the core protocol,
appearing to make use of the TrueColor visual class and relevant fields of the
XVisualInfo structure as one would expect of an ordinary TrueColor visual.
Rendering to DeepColor windows using the core protocol, however, is loosely
defined.
The true format of the visual and window is defined by the extension, with
additional requests provided by the extension to determine relevant attributes
for use with external graphics APIs. The server is responsible for reconciling
non-DeepColor aware core protocol rendering with the true format of the
window.
GetImage and PutImage requests must read and write pixels using a transfer
function between the core protocol exposed TrueColor format and the true format
of the window. The exact transfer function used, however, is determined by the
implementation, meaning that results should be "reasonable" but are essentially
undefined.
If any other core rendering is attempted, the expectation is as if one used
GetImage to read from the window into a pixmap, performed the rendering there,
and then used PutImage to write the results back.
DeepColor visuals are returned later in the connection block than real TrueColor
visuals, with the intent of reducing the chance that existing applications
choose them by mistake and incurring unnecessary overhead.
3. Errors
The DeepColor extension does not define any new errors.
4. Protocol Types
PIXELFORMAT { FP_R16G16B16A16
UINT_R16G16B16A16
UINT_A2R10G10B10
UINT_A2B10G10R10 }
These values are used to indicate a pixel format/memory layout associated
with a given DeepColor visual.
VISUALINFO { core_visual_id: VISUALID
pixel_format: PIXELFORMAT }
A pairing of a VISUALID with a PIXELFORMAT, used for returning the pixel
format of a queried DeepColor visual.
COLORSPACETYPE { Undefined
scRGB_Linear
BT2020_Linear
BT2020_PQ
BT2020_HLG
DCI_P3_D60_Linear
DCI_P3_D65_Linear
DCI_P3_D60_Gamma
DCI_P3_D65_Gamma
ACES_AP0_Linear
ACES_AP1_Linear }
These values are used to indicate a color space/encoding associated with a
given DeepColor window. Some need an additional gamma specification to be
complete in their description of the encoding.
Undefined is a sentinel value in the event that a color space/encoding could
not be specified.
scRGB_Linear describes an scRGB color space with linear OETF. scRGB uses the
same primaries and white point as sRGB, and the linear encoding is best used
with an FP16 pixel format.
BT2020_Linear describes a BT.2020 color space with linear OETF. BT.2020
defines its own primaries with a D65 white point, and the linear encoding is
best used with an FP16 pixel format.
BT2020_PQ describes a BT.2020 color space with SMPTE ST.2084 Perceptual
Quantizer (PQ) OETF, also known as HDR10. BT.2020 defines its own primaries
with a D65 white point, and the nonlinear encoding is best used with an
unsigned integer pixel format.
BT2020_HLG describes a BT.2020 color space with ARIB STD-B67 Hybrid
Log-Gamma (HLG) OETF, also known as HLG10. BT.2020 defines its own primaries
with a D65 white point, and the nonlinear encoding is best used with an
unsigned integer pixel format.
DCI_P3_D60_Linear describes a DCI-P3 color space with D60 white point and
linear OETF. DCI-P3 defines its own primaries, and the linear encoding is
best used with an FP16 pixel format.
DCI_P3_D65_Linear describes a DCI-P3 color space with D65 white point and
linear OETF. DCI-P3 defines its own primaries, and the linear encoding is
best used with an FP16 pixel format.
DCI_P3_D60_Gamma describes a DCI-P3 color space with D60 white point and
gamma OETF. DCI-P3 defines its own primaries, and the nonlinear encoding is
best used with an unsigned integer pixel format. The exact gamma value
varies and is specified separately.
DCI_P3_D65_Gamma describes a DCI-P3 color space with D65 white point and
gamma OETF. DCI-P3 defines its own primaries, and the nonlinear encoding is
best used with an unsigned integer pixel format. The exact gamma value
varies and is specified separately.
ACES_AP0_Linear describes an ACES colorspace with AP0 primaries and linear
OETF. ACES uses a D60 white point, and the linear encoding is best used with
an FP16 pixel format.
ACES_AP1_Linear describes an ACES colorspace with AP1 primaries and linear
OETF. ACES uses a D60 white point, and the linear encoding is best used with
an FP16 pixel format.
COLORSPACE { type: COLORSPACETYPE
gamma: FIXED }
A pairing of a color space/encoding type with a gamma value. Some color
space/encoding types require an associated gamma value to fully define the
encoding. If 'type' is a color space/encoding type that does not require a
gamma value, 'gamma' is undefined.
COLORSPACEPRIORITY { colorspace: COLORSPACE
score: CARD32 }
A pairing of a color space/encoding with an associated score, used for
prioritizing color spaces/encodings when represented in a list.
DPCSELECTMASK { DPCDisplayChangeNotifyMask,
DPCCompositorChangeNotifyMask,
DPCWindowChangeNotifyMask }
5. Extension Initialization
The name of this extension is "DEEP-COLOR".
DPCQueryVersion
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.
6. Extension Requests
DPCSelectInput
window: WINDOW
enable: SETofDPCSELECTMASK
Errors: Window, Value
If 'enable' is DPCDisplayChangeNotifyMask, DPCDisplayChangeNotify events
will be sent when the capabilities of a display associated with the screen
change. DPCDisplayChangeNotify events may also be sent when this request
executes if the display capabilities have changed since the client
connected, to avoid race conditions.
If 'enable' is DPCCompositorChangeNotifyMask, DPCCompositorChangeNotify
events will be sent when the capabilities of the compositor associated with
the screen changes. DPCCompositorChangeNotify events may also be sent when
this request executes if the compositor capabilities have changed since the
client connected, to avoid race conditions.
If 'enable' is DPCWindowChangeNotifyMask, DPCWindowChangeNotify events will
be sent when the color space/encoding being used for rendering into the
requested window changes. DPCWindowChangeNotify events may also be sent when
this request executes if the color space/encoding being used for rendering
has changed since the client connected, to avoid race conditions.
DPCGetVisualInfo
visual_list: LISTofVISUALID
=>
per_visual_info: LISTofVISUALINFO
Non-DeepColor visuals specified in LISTofVISUALID will not be returned in the
resulting LISTofVISUALINFO.
DPCGetDisplayCapabilities
output: OUTPUT
=>
colorspace_list: LISTofCOLORSPACEPRIORITY
Errors: Output
DPCGetDisplayCapabilities retrieves a list of color spaces/encodings
and their associated scores from a given output, representing the
capabilities and preferences of the display as determined by the server.
Every color space/encoding represented in colorspace_list must be supported
by the display corresponding to the output, but those with higher associated
scores are preferred. The set of color space/encodings represented in
colorspace_list cannot change after server initialization, but the
associated scores may change. Although the set of color spaces/encodings
returned for every output must be identical at any given time, the
associated scores may vary from output to output.
A composite manager must use a color space/encoding supported by the
display(s) when compositing into the target window.
DPCGetWindowDisplayCapabilities
window: WINDOW
=>
output: OUTPUT
colorspace_list: LISTofCOLORSPACEPRIORITY
Errors: Window
DPCGetWindowDisplayCapabilities functions identically to
DPCGetDisplayCapabilities, but rather than explicitly specifying an output,
the user must specify a window. The request then retrieves a list of color
spaces/encodings and their associated scores from the output upon which the
window is centered.
Every color space/encoding represented in colorspace_list must be supported
by the display corresponding to the output, but those with higher associated
scores are preferred. The set of color space/encodings represented in
colorspace_list cannot change after server initialization, but the
associated scores may change. Although the set of color spaces/encodings
returned for every output must be identical at any given time, the
associated scores may vary from output to output.
A composite manager must use a color space/encoding supported by the
display(s) when compositing into the target window.
DPCGetCompositorCapabilities
output: OUTPUT
=>
colorspace_list: LISTofCOLORSPACEPRIORITY
Errors: Output
DPCGetCompositorCapabilities retrieves a list of color spaces/encodings and
their associated scores from a given output, representing the capabilities
and preferences of composition (whether provided by a composite manager or
in-server compositing).
The set of color spaces/encodings represented in colorspace_list must be
supported by the compositor, but those with higher associated scores are
preferred for a given output. Although the set of color spaces/encodings
returned for every output must be identical at any given time, the
associated scores may vary from output to output.
An application must use a color space/encoding supported by the compositor
when choosing a color space/encoding to use for rendering into a DeepColor
window.
DPCGetWindowCompositorCapabilities
window: WINDOW
=>
output: OUTPUT
colorspace_list: LISTofCOLORSPACEPRIORITY
Errors: Window
DPCGetWindowCompositorCapabilities functions identically to
DPCGetCompositorCapabilities, but rather than explicitly specifying an
output, the user must specify a window. The request then retrieves a list of
color spaces/encodings and their associated scores from the output upon
which the window is centered.
The set of color spaces/encodings represented in colorspace_list must be
supported by the compositor, but those with higher associated scores are
preferred for a given output. Although the set of color spaces/encodings
returned for every output must be identical at any given time, the
associated scores may vary from output to output.
An application must use a color space/encoding supported by the compositor
when choosing a color space/encoding to use for rendering into a DeepColor
window.
DPCOverrideCompositorCapabilities
output: OUTPUT
colorspace_list: LISTofCOLORSPACEPRIORITY
Errors: Output
Used by a composite manager to override the set of color spaces/encodings
and associated scores for composition for a given output before using
RedirectSubwindows on the root window. Changes will not take effect from a
client perspective until a subsequent redirection of the root window
hierarchy has completed.
DPCCompositorChangeNotify events will be generated on the appropriate root
window when the compositor capabilities are changed by this call. The
changes do not take effect until after the subsequent redirection of the
root window hierarchy has completed, so the event will also not be generated
until then.
The set of outputs represented in 'overrides' must be complete, and the set
of color spaces/encodings associated with each of them must be identical or
the capabilities will be cleared instead of updated to the new set, still
generating a DPCCompositorChangeNotify event.
The associated scores may vary from output to output.
DPCGetWindowColorspace
window: WINDOW
=>
colorspace: COLORSPACE
Errors: Window, Match
Retrieves the color space/encoding being used for rendering into a specified
DeepColor window.
'window' must be a DeepColor window or a Match error results.
DPCSetWindowColorspace
window: WINDOW
colorspace: COLORSPACE
Errors: Window, Match
Sets the color space/encoding being used for rendering into a specified
DeepColor window.
For applications, this must be an option supported by the compositor, and
must be updated in response to DPCCompositorChangeNotify events. Rendering
using options not supported by the compositor will result in undefined
graphical behavior.
Composite managers are expected to use this request to indicate to the
server which color space is being used for rendering into the target window.
In this case, the option must be supported by the display. Rendering using
options not supported by the display will result in undefined graphical
behavior.
'window' must be a DeepColor window or a Match error results.
DPCWindowChangeNotify events will be generated on the window when the color
space/encoding is changed by this call.
7. Extension Events
Events are delivered via the Generic Event Extension. If the Generic Event
Extension is not present, the events specified here will not be delivered.
DPCDisplayChangeNotify
requester: WINDOW window requesting notification
output: OUTPUT output affected by change
colorspace_list: LISTofCOLORSPACEPRIORITY updated display capabilities
This event is generated whenever the capabilities of a display associated
with the screen change. Note that the set of color spaces/encodings
represented in colorspace_list cannot change after server initialization,
but the associated scores may change. The set of color spaces/encodings
supported between the outputs must be identical, but the scores may vary.
Separate events will be received for each output.
Composite managers may choose to listen for this event to choose a more
favorable color space/encoding for rendering into the target window.
DPCCompositorChangeNotify
requester: WINDOW window requesting notification
output: OUTPUT output affected by change
colorspace_list: LISTofCOLORSPACEPRIORITY updated compositor capabilities
This event is generated whenever the capabilities of the compositor
associated with the screen change. Note that the capabilities of all outputs
associated with the screen change at the same time, and that the set of
color spaces/encodings supported between them must be identical, but the
scores may vary. Separate events will be received for each output.
This event may be generated if a composite manager overrides the in-server
compositing capabilities via DPCOverrideCompositorCapabilities, if the
server takes over again after the root window hierarchy has been
unredirected, or after the capabilities have been cleared due to a composite
manager failing to properly override the compositor capabilities before
redirecting the root window hierarchy.
Applications must listen to this event and change which color space/encoding
they are using for rendering if their current selection is no longer
supported. They may choose a more favorable color space/encoding even if
their current selection is still supported.
DPCWindowChangeNotify
requester: WINDOW window requesting notification
window: WINDOW window affected by change
colorspace: COLORSPACE updated color space/encoding
This event is generated whenever the color space/encoding being used for
rendering into a requested window changes.
Composite managers must listen to this event to accurately adjust their
composition of application windows into the target window. Failure to adjust
in response to DPCWindowChangeNotify events could result in undefined
graphical behavior.
8. Protocol Encoding
This document uses the same syntactic conventions as the core X protocol
encoding document.
8.1 Common Types
PIXELFORMAT
0x00000000 FP_R16G16B16A16
0x00000001 UINT_R16G16B16A16
0x00000002 UINT_A2R10G10B10
0x00000003 UINT_A2B10G10R10
VISUALINFO
4 VISUALID
4 PIXELFORMAT
COLORSPACETYPE
0x00000000 Undefined
0x00000001 scRGB_Linear
0x00000002 BT2020_Linear
0x00000003 BT2020_PQ
0x00000004 BT2020_HLG
0x00000005 DCI_P3_D60_Linear
0x00000006 DCI_P3_D65_Linear
0x00000007 DCI_P3_D60_Gamma
0x00000008 DCI_P3_D65_Gamma
0x00000009 ACES_AP0_Linear
0x0000000a ACES_AP1_Linear
COLORSPACE
4 COLORSPACETYPE
4 FIXED gamma
COLORSPACEPRIORITY
8 COLORSPACE
4 CARD32 score
4 unused
DPCSELECTMASK
0x0001 DPCDisplayChangeNotifyMask
0x0002 DPCCompositorChangeNotifyMask
0x0004 DPCWindowChangeNotifyMask
8.2 Protocol Requests
DPCQueryVersion
1 CARD8 major opcode
1 0 DPC opcode
2 3 request length
4 CARD32 client-major-version
4 CARD32 client-minor-version
=>
1 1 reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 major-version
4 CARD32 minor-version
DPCSelectInput
1 CARD8 major opcode
1 1 DPC opcode
2 3 request length
4 WINDOW window
2 SETofDPCSELECTMASK enable
2 unused
DPCGetVisualInfo
1 CARD8 opcode
1 2 DPC opcode
2 2+n request length
4 n number of VISUALIDs in list
4n CARD32 VISUALIDs
=>
1 1 reply
1 unused
2 CARD16 sequence number
4 2v reply length
4 v number of VISUALINFOs in list
20 unused
8v LISTofVISUALINFO items
DPCGetDisplayCapabilities
1 CARD8 opcode
1 3 DPC opcode
2 2 request length
4 OUTPUT output
=>
1 1 reply
1 unused
2 CARD16 sequence number
4 4c reply length
4 c number of COLORSPACEPRIORITYs in list
20 unused
16c LISTofCOLORSPACEPRIORITY colorspace_list
DPCGetWindowDisplayCapabilities
1 CARD8 opcode
1 4 DPC opcode
2 2 request length
4 WINDOW window
=>
1 1 reply
1 unused
2 CARD16 sequence number
4 4c reply length
4 OUTPUT output
4 c number of COLORSPACEPRIORITYs in list
16 unused
16c LISTofCOLORSPACEPRIORITY colorspace_list
DPCGetCompositorCapabilities
1 CARD8 opcode
1 5 DPC opcode
2 2 request length
4 OUTPUT output
=>
1 1 reply
1 unused
2 CARD16 sequence number
4 4c reply length
4 c number of COLORSPACEPRIORITYs in list
20 unused
16c LISTofCOLORSPACEPRIORITY colorspace_list
DPCGetWindowCompositorCapabilities
1 CARD8 opcode
1 6 DPC opcode
2 2 request length
4 WINDOW window
=>
1 1 reply
1 unused
2 CARD16 sequence number
4 4c reply length
4 OUTPUT output
4 c number of COLORSPACEPRIORITYs in list
16 unused
16c LISTofCOLORSPACEPRIORITY colorspace_list
DPCOverrideCompositorCapabilities
1 CARD8 opcode
1 7 DPC opcode
2 4+4c request length
4 OUTPUT output
4 c number of COLORSPACEPRIORITYs in list
4 unused
16c LISTofCOLORSPACEPRIORITY colorspace_list
DPCGetWindowColorspace
1 CARD8 opcode
1 8 DPC opcode
2 2 request length
4 WINDOW window
=>
1 1 reply
1 unused
2 CARD16 sequence number
4 0 reply length
8 COLORSPACE colorspace
DPCSetWindowColorspace
1 CARD8 opcode
1 9 DPC opcode
2 4 request length
4 WINDOW window
8 COLORSPACE colorspace
8.3 Protocol Events
DPC is the major opcode for the extension, as returned by XQueryExtension.
DPCDisplayChangeNotify
1 35 (GenericEvent) type
1 DPC extension
2 CARD16 sequence number
4 4c length
2 0 evtype
2 unused
4 WINDOW requester
4 OUTPUT output
4 c number of COLORSPACEPRIORITYs in list
8 unused
16c LISTofCOLORSPACEPRIORITY colorspace_list
DPCCompositorChangeNotify
1 35 (GenericEvent) type
1 DPC extension
2 CARD16 sequence number
4 4c length
2 1 evtype
2 unused
4 WINDOW requester
4 OUTPUT output
4 c number of COLORSPACEPRIORITYs in list
8 unused
16c LISTofCOLORSPACEPRIORITY colorspace_list
DPCWindowChangeNotify
1 35 (GenericEvent) type
1 DPC extension
2 CARD16 sequence number
4 0 length
2 2 evtype
2 unused
4 WINDOW requester
4 COLORSPACE colorspace
12 unused
9. Issues
This spec does not address the suggestion that window color space/encoding
should reflect that of the next frame. It is difficult to determine what the
"next frame" is without the Present extension, and a concrete solution has yet
to be found.
* Perhaps this functionality could be the domain of an interaction between
the Present extension and DeepColor-aware clients, where clients hand off
the responsibility for finalizing the color space/encoding of a window to
the Present extension, which would atomically update it with the
presentation of the next frame before generating DPCWindowChangeNotify.
10. References
[RANDR]
Gettys, Jim and Keith Packard, "The X Resize, Rotate and Reflect Extension",
2009-10-05,
http://cgit.freedesktop.org/xorg/proto/renderproto/tree/renderproto.txt
[COMPOSITE]
Packard, Keith and Deron Johnson, "Composite Extension", 2007-07-03,
https://www.x.org/releases/current/doc/compositeproto/compositeproto.txt
[RENDER]
Packard, Keith, "The X Rendering Extension", 2009-07-15,
http://cgit.freedesktop.org/xorg/proto/renderproto/tree/renderproto.txt
On Mon, 25 Sep 2017, Adam Jackson wrote:
> On Mon, 2017-08-14 at 19:17 -0700, Alex Goins wrote:
> > We brainstormed all of the suggestions amongst ourselves, and have a revised
> > version of the spec. It also includes some changes of our own.
> >
> > Unfortunately, we weren't able to bottom out on everything (most notably the
> > masquerading DeepColor/TrueColor visuals), but the suggestions we haven't yet
> > implemented in the spec are included in the issues section, along with our
> > outstanding concerns. We will likely need more discussion over email or at XDC
> > to make sure that these suggestions are fully fleshed out.
>
> There was a very productive discussion about this at XDC, so for the
> benefit of those who were unable to attend - and to ensure we're all on
> the same page - here's a quick summary.
>
> 1) No new visual class. The risk of client incompatibility is
> unacceptable. DeepColor visuals will appear to be TrueColor in the core
> protocol, but rendering to them with the core protocol is essentially
> undefined. To be precise, GetImage and PutImage must do something
> reasonable (though the exact transfer function is an implementation
> detail), and if any other core rendering is attempted, the expectation
> is as if one did GetImage to a pixmap, performed the rendering there,
> and PutImage'd the result back. Rendering that crosses visuals is
> already undefined in the protocol.
>
> 2) No window properties. Equivalent state and transitions will be
> encoded as new requests in the DeepColor extension itself.
>
> 3) Clients will be protected from accidentally selecting a DeepColor
> visual in the usual way, by returning those visuals later in the list
> than real TrueColor visuals. The Composite extension had difficulty
> with some clients that opted for the visual with the most rgb bits, but
> as the new visuals will appear indistinguishable to the core protocol
> this should not arise, and the "pick the first one that matches"
> heuristic in most toolkits should continue to do the right thing.
>
> 4) We can add a hack to libX11 a la XLIB_SKIP_ARGB_VISUALS to forcibly
> conceal DeepColor visuals from buggy clients. We will not do so for
> libxcb, which is a direct protocol binding not an application
> interface; you asked for it, you got it.
>
> 5) DeepColor visuals will not have a corresponding GLX visual. The GLX
> spec very carefully allows fbconfigs to have more r/g/b bits than any
> visual they might point to, so apps that want to do HDR GL will need to
> select by fbconfig; this should be no burden, as this is what you
> already have to do for float pbuffers. The existing visual select group
> mechanism can be used to ensure non-HDR clients do not accidentally
> select an HDR visual.
>
> 6) GLX requires that the context's rendering type match the drawable's
> fbconfig. This might have made some sense for color index vs. RGBA, but
> GLX_ARB_fbconfig_float defines "float RGBA" as yet a third type. For
> modern implementations this is a fairly daft limitation, since they can
> usually render to arbitrary formats for non-window-system FBOs. So
> rather than require a compositor to use multiple contexts and somehow
> pass resources between them, we can port the EGL_KHR_no_config_context
> extension to GLX. A draft spec for this, should anybody besides Xorg
> shipping a GLX implementation wish to review it, is here:
>
> https://github.com/KhronosGroup/OpenGL-Registry/pull/102
>
> - ajax
>
More information about the xorg-devel
mailing list