[RFC] DeepColor Visual Class Extension
Alex Goins
agoins at nvidia.com
Sat Nov 11 04:53:05 UTC 2017
> On Fri, 2017-11-03 at 21:04 -0700, Alex Goins wrote:
>
> > > > DPCCompositorChangeNotify
> > > >
> > > > requester: WINDOW window requesting notification
> > > > output: OUTPUT output affected by change
> > > > colorspace_list: LISTofCOLORSPACEPRIORITY updated compositor capabilities
> > >
> > > Likewise I think this event should return a list.
> >
> > My initial reason for not having a list was that it would result in a list of
> > lists. Is there a precedent for this? It seems like it would complicate the
> > encoding unless the nested list is fixed length.
>
> It _is_ fixed length, though, isn't it? Every output has to support the
> same set of colorspaces.
You're right, it's at least fixed length relative to the other lists. I think it
works, just complicates the padding. I took a shot at it.
This version also includes events for tracking display and compositor changes as
a window moves between outputs.
Diff is followed by full text.
Thanks!
-Alex
---
Diff:
diff --git a/deepcolorproto.txt b/deepcolorproto.txt
index 87fbf2d..64a592c 100644
--- a/deepcolorproto.txt
+++ b/deepcolorproto.txt
@@ -194,8 +194,17 @@ COLORSPACEPRIORITY { colorspace: COLORSPACE
A pairing of a color space/encoding with an associated score, used for
prioritizing color spaces/encodings when represented in a list.
+OVERRIDE { output: OUTPUT
+ colorspace_list: LISTofCOLORSPACEPRIORITY }
+
+ A pairing of an output with a list of colorspaces and associated scores,
+ used for overriding compositor capabilities, or receiving information
+ thereof.
+
DPCSELECTMASK { DPCDisplayChangeNotifyMask,
+ DPCWindowDisplayChangeNotifyMask,
DPCCompositorChangeNotifyMask,
+ DPCWindowCompositorChangeNotifyMask,
DPCWindowChangeNotifyMask }
5. Extension Initialization
@@ -231,11 +240,25 @@ The name of this extension is "DEEP-COLOR".
change. DPCDisplayChangeNotify events will be sent when this request
executes to avoid potential race conditions when a client connects.
+ If 'enable' is DPCWindowDisplayChangeNotifyMask,
+ DPCWindowDisplayChangeNotify events will be sent when the output upon which
+ the requesting window is centered, or the capabilities of its associated
+ display, changes. A DPCWindowDisplayChangeNotify event will be sent when
+ this request executes to avoid potential race conditions when a client
+ connects.
+
If 'enable' is DPCCompositorChangeNotifyMask, DPCCompositorChangeNotify
events will be sent when the capabilities of the compositor associated with
- the screen changes. DPCCompositorChangeNotify events will be sent when this
+ the screen changes. A DPCCompositorChangeNotify event will be sent when this
request executes to avoid potential race conditions when a client connects.
+ If 'enable' is DPCWindowCompositorChangeNotifyMask,
+ DPCWindowCompositorChangeNotify events will be sent when the output upon
+ which the requesting window is centered, or the capabilities of its
+ associated compositor, changes. A DPCWindowCompositorChangeNotify event will
+ be sent when this request executes to avoid potential race conditions when a
+ client connects.
+
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 will be sent when
@@ -291,7 +314,10 @@ The name of this extension is "DEEP-COLOR".
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.
+ window is centered. In the case of a tie, the primary output is preferred,
+ if available, otherwise the server may choose any output upon which the
+ window is centered. For the root window, the primary output is used if
+ available, otherwise the selection logic is treated as any other window.
Every color space/encoding represented in colorspace_list must be supported
by the display corresponding to the output, but those with higher associated
@@ -343,7 +369,11 @@ The name of this extension is "DEEP-COLOR".
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.
+ which the window is centered. In the case of a tie, the primary output is
+ preferred, if available, otherwise the server may choose any output upon
+ which the window is centered. For the root window, the primary output is
+ used if available, otherwise the selection logic is treated as any other
+ window.
The set of color spaces/encodings represented in colorspace_list must be
supported by the compositor, but those with higher associated scores are
@@ -358,33 +388,37 @@ The name of this extension is "DEEP-COLOR".
DPCOverrideCompositorCapabilities
- output: OUTPUT
- colorspace_list: LISTofCOLORSPACEPRIORITY
+ override_list: LISTofOVERRIDE
Errors: Output, Match
Used by a composite manager to override the set of possible color
- spaces/encodings and associated scores for composition for a given output.
+ spaces/encodings and associated scores for composition for all outputs.
If used before requesting RedirectSubwindows on the root window, changes
will not take effect until a subsequent redirection of the root window
- hierarchy by the requester has completed. Color spaces/encodings associated
- with each output must be identical, but scores may vary. If a composite
- manager fails to fulfill these requirements before requesting
- RedirectSubwindows on the root window, the server will instead empty the set
- of capabilities on each output, generating a DPCCompositorChangeNotify event
- for each.
+ hierarchy by the requester has completed. If used after the root window
+ hierarchy has been redirected by the requester, changes take effect
+ immediately.
- If used after the root window hierarchy has been redirected by the
- requester, changes take effect immediately. The set of color
- spaces/encodings specified must match those of other outputs on the screen,
- or a Match error results. Scores, however, may differ from other outputs.
+ The set of outputs must be complete, or an Output error results.
- DPCCompositorChangeNotify events will be generated on the appropriate root
- window when the compositor capabilities are changed by this request. If
- applicable, the changes do not take effect until after the subsequent
- redirection of the root window hierarchy has completed, thereby delaying the
- generation of the event.
+ The set of color spaces/encodings associated with each output must be
+ identical, but scores more vary. If this requirement is not fulfilled, a
+ Match error results.
+
+ If a composite manager fails to successfully use this request before
+ requesting RedirectSubwindows on the root window, the server will instead
+ empty the set of capabilities on each output, generating a
+ DPCCompositorChangeNotify event along with DPCWindowCompositorChangeNotify
+ events.
+
+ A DPCCompositorChangeNotify event, along with
+ DPCWindowCompositorChangeNotify events, will be generated on the appropriate
+ root window/outputs when the compositor capabilities are changed by this
+ request. If applicable, the changes do not take effect until after the
+ subsequent redirection of the root window hierarchy has completed, thereby
+ delaying the generation of the events.
DPCGetWindowColorspace
@@ -471,32 +505,55 @@ The name of this extension is "DEEP-COLOR".
DPCDisplayChangeNotify
- requester: WINDOW window requesting notification
- output: OUTPUT output affected by change
+ 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.
+ 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 listen to this event to choose a more favorable color
+ space/encoding for rendering into the target window.
+
+
+ DPCWindowDisplayChangeNotify
+
+ requester: WINDOW requesting notification
+ output: OUTPUT output upon which window is centered
+ colorspace_list: LISTofCOLORSPACEPRIORITY updated display capabilities
- Composite managers may choose to listen for this event to choose a more
- favorable color space/encoding for rendering into the target window.
+ This event is generated whenever the output upon which the requesting window
+ is centered, or the capabilities of its associated display, changes. In the
+ case of a tie, the previously chosen output (if applicable) is preferred,
+ followed by the primary output, if available, otherwise the server may
+ choose any output upon which the window is centered.
+
+ 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.
+
+ Composite managers may listen to 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
+ requester: WINDOW window requesting notification
+ override_list: LISTofOVERRIDE updated outputs and 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.
+ 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.
This event may be generated if a composite manager overrides the in-server
compositing capabilities via DPCOverrideCompositorCapabilities, if the
@@ -515,17 +572,38 @@ The name of this extension is "DEEP-COLOR".
Applications should 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.
+ longer supported or preferred.
Composite managers may listen to this event in order to override scores of
new outputs with more accurate selections.
+ DPCWindowCompositorChangeNotify
+
+ requester: WINDOW window requesting notification
+ output: OUTPUT output upon which the window is centered
+ colorspace_list: LISTofCOLORSPACEPRIORITY updated compositor capabilities
+
+ This event is generated whenever the output upon which the requesting window
+ is centered, or the capabilities of its associated compositor, changes. In
+ the case of a tie, the previously chosen output (if applicable) is
+ preferred, followed by the primary output, if available, otherwise the
+ server may choose any output upon which the window is centered.
+
+ 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.
+
+ Applications may listen to this event as an alternative to the more general
+ DPCCompositorChangeNotify, and change which color space/encoding they are
+ using for rendering if their current selection is no longer supported or
+ preferred.
+
+
DPCWindowChangeNotify
- requester: WINDOW window requesting notification
- window: WINDOW window affected by change
+ 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
@@ -588,11 +666,21 @@ encoding document.
4 unused
+ OVERRIDE
+
+ 4 OUTPUT output
+ 4 c number of COLORSPACEPRIORITYs in list
+ 8 unused
+ 16c LISTofCOLORSPACEPRIORITY colorspace_list
+
+
DPCSELECTMASK
0x0001 DPCDisplayChangeNotifyMask
- 0x0002 DPCCompositorChangeNotifyMask
- 0x0004 DPCWindowChangeNotifyMask
+ 0x0002 DPCWindowDisplayChangeNotifyMask
+ 0x0004 DPCCompositorChangeNotifyMask
+ 0x0008 DPCWindowCompositorChangeNotifyMask
+ 0x0010 DPCWindowChangeNotifyMask
8.2 Protocol Requests
@@ -709,11 +797,12 @@ encoding document.
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
+ 2 unused
+ 4 4+4c+4o(c+1) request length
+ 4 o number of OVERRIDEs in list
+ 4 c number of COLORSPACEPRIORITYs/OVERRIDE
+ 16c unused
+ o(16(c+1)) LISTofOVERRIDE override_list
DPCGetWindowColorspace
@@ -766,7 +855,7 @@ DPC is the major opcode for the extension, as returned by XQueryExtension.
16c LISTofCOLORSPACEPRIORITY colorspace_list
- DPCCompositorChangeNotify
+ DPCWindowDisplayChangeNotify
1 35 (GenericEvent) type
1 DPC extension
@@ -781,13 +870,43 @@ DPC is the major opcode for the extension, as returned by XQueryExtension.
16c LISTofCOLORSPACEPRIORITY colorspace_list
+ DPCCompositorChangeNotify
+
+ 1 35 (GenericEvent) type
+ 1 DPC extension
+ 2 CARD16 sequence number
+ 4 MAX(0,4(c-1))+4o(c+1) length
+ 2 2 evtype
+ 2 unused
+ 4 WINDOW requester
+ 4 o number of OVERRIDEs in list
+ 4 c number of COLORSPACEPRIORITYs/OVERRIDE
+ 8+MAX(0,16(c-1)) unused
+ o(16(c+1)) LISTofOVERRIDE override_list
+
+
+ DPCWindowCompositorChangeNotify
+
+ 1 35 (GenericEvent) type
+ 1 DPC extension
+ 2 CARD16 sequence number
+ 4 4c length
+ 2 3 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 4 evtype
2 unused
4 WINDOW requester
4 COLORSPACE colorspace
@@ -809,6 +928,12 @@ currently included in this spec, require SMPTE 2094 dynamic metadata, which can
change from frame to frame. This could be updated with a new request similar to
DPCSetNextPresentColorspace.
+Adding SMPTE 2094 to this extension would require synchronizing direct rendering
+with X protocol, which is undesirable. Likewise, SMPTE 2086 handles metadata
+that does not directly pertain to the stored format of the pixel data, so it may
+be outside the scope of this extension. Perhaps there should be a GLX extension
+to mirror the EGL and Vulkan extensions?
+
In the case of a mismatch between capabilities and a color space/encoding being
used, there is a suggestion to restrict the image presented on the screen to the
precision of the associated core visual, but the mechanism with which this could
---
Full Text:
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, RROutputChangeNotify event, and Output error.
The Composite extension is referenced for interaction with RedirectSubwindows
and UnredirectSubwindows.
The Present extension is referenced for interaction with the PresentPixmap
request.
The Damage extension is referenced for interaction the DamageNotify event.
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. The
exact content resulting from rendering to DeepColor windows using the core
protocol, however, is up to the implementation.
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 actual
DeepColor format of the window. The transfer function must be bijective -- that
is, a pixel value must remain the same when transformed to the DeepColor format
and back. 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
FLOAT32
A 32-bit value in IEEE floating point format.
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.
The OETF (Optical Electric Transfer Function), or inverse EOTF, defines the
encoding of optical intensities to stored values. A commonly known OETF is
that used by sRGB, typically referred to as "gamma." OETFs referred to here
are analogous to that used by sRGB, albeit often more complex and varied.
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: FLOAT32 }
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, in which case 'gamma' must be a value > 1.0. 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.
OVERRIDE { output: OUTPUT
colorspace_list: LISTofCOLORSPACEPRIORITY }
A pairing of an output with a list of colorspaces and associated scores,
used for overriding compositor capabilities, or receiving information
thereof.
DPCSELECTMASK { DPCDisplayChangeNotifyMask,
DPCWindowDisplayChangeNotifyMask,
DPCCompositorChangeNotifyMask,
DPCWindowCompositorChangeNotifyMask,
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 will be sent when this request
executes to avoid potential race conditions when a client connects.
If 'enable' is DPCWindowDisplayChangeNotifyMask,
DPCWindowDisplayChangeNotify events will be sent when the output upon which
the requesting window is centered, or the capabilities of its associated
display, changes. A DPCWindowDisplayChangeNotify event will be sent when
this request executes to avoid potential race conditions when a client
connects.
If 'enable' is DPCCompositorChangeNotifyMask, DPCCompositorChangeNotify
events will be sent when the capabilities of the compositor associated with
the screen changes. A DPCCompositorChangeNotify event will be sent when this
request executes to avoid potential race conditions when a client connects.
If 'enable' is DPCWindowCompositorChangeNotifyMask,
DPCWindowCompositorChangeNotify events will be sent when the output upon
which the requesting window is centered, or the capabilities of its
associated compositor, changes. A DPCWindowCompositorChangeNotify event will
be sent when this request executes to avoid potential race conditions when a
client connects.
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 will be sent when
this request executes to avoid potential race conditions when a client
connects.
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 should use a color space/encoding supported by the
display(s) when choosing a color space/encoding to use for composition into
the target window, or the contents may not be displayed accurately.
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. In the case of a tie, the primary output is preferred,
if available, otherwise the server may choose any output upon which the
window is centered. For the root window, the primary output is used if
available, otherwise the selection logic is treated as any other window.
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 should use a color space/encoding supported by the
display(s) when choosing a color space/encoding to use for composition into
the target window, or the contents may not be displayed accurately.
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 should use a color space/encoding supported by the compositor
when choosing a color space/encoding to use for rendering into a DeepColor
window, or the contents may not be composited accurately.
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. In the case of a tie, the primary output is
preferred, if available, otherwise the server may choose any output upon
which the window is centered. For the root window, the primary output is
used if available, otherwise the selection logic is treated as any other
window.
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 should use a color space/encoding supported by the compositor
when choosing a color space/encoding to use for rendering into a DeepColor
window, or the contents may not be composited accurately.
DPCOverrideCompositorCapabilities
override_list: LISTofOVERRIDE
Errors: Output, Match
Used by a composite manager to override the set of possible color
spaces/encodings and associated scores for composition for all outputs.
If used before requesting RedirectSubwindows on the root window, changes
will not take effect until a subsequent redirection of the root window
hierarchy by the requester has completed. If used after the root window
hierarchy has been redirected by the requester, changes take effect
immediately.
The set of outputs must be complete, or an Output error results.
The set of color spaces/encodings associated with each output must be
identical, but scores more vary. If this requirement is not fulfilled, a
Match error results.
If a composite manager fails to successfully use this request before
requesting RedirectSubwindows on the root window, the server will instead
empty the set of capabilities on each output, generating a
DPCCompositorChangeNotify event along with DPCWindowCompositorChangeNotify
events.
A DPCCompositorChangeNotify event, along with
DPCWindowCompositorChangeNotify events, will be generated on the appropriate
root window/outputs when the compositor capabilities are changed by this
request. If applicable, the changes do not take effect until after the
subsequent redirection of the root window hierarchy has completed, thereby
delaying the generation of the events.
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 should be an option supported by the compositor, and
should be updated in response to DPCCompositorChangeNotify events.
Rendering using options not supported by the compositor will produce results
that may not be composited accurately.
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 should be supported by the display. Rendering using
options not supported by the display will produce results that may not be
displayed accurately.
'window' must be a DeepColor window or a Match error results.
If 'colorspace' includes a 'colorspacetype' that makes use of the 'gamma'
field, and 'gamma' is not a value > 1.0, a Match error results.
DPCWindowChangeNotify events will be generated on the window when the color
space/encoding is changed by this request.
DPCSetNextPresentColorspace
window: WINDOW
colorspace: COLORSPACE
Errors: Window, Match
Sets the color space/encoding being used for rendering into a specified
DeepColor window, deferred until atomically updated when the next
PresentPixmap presentation completes.
If the Present extension is not present, the changes from this request will
not take effect.
For applications, this should be an option supported by the compositor, and
should be updated in response to DPCCompositorChangeNotify events.
Rendering using options not supported by the compositor at any given time
will produce results that may not be composited accurately.
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 should be supported by the display. Rendering using
options not supported by the display will produce results that may not be
displayed accurately.
'window' must be a DeepColor window or a Match error results.
If 'colorspace' includes a 'colorspacetype' that makes use of the 'gamma'
field, and 'gamma' is not a value > 1.0, a Match error results.
DPCWindowChangeNotify events will be generated on the window when the color
space/encoding is changed by this request.
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 listen to this event to choose a more favorable color
space/encoding for rendering into the target window.
DPCWindowDisplayChangeNotify
requester: WINDOW requesting notification
output: OUTPUT output upon which window is centered
colorspace_list: LISTofCOLORSPACEPRIORITY updated display capabilities
This event is generated whenever the output upon which the requesting window
is centered, or the capabilities of its associated display, changes. In the
case of a tie, the previously chosen output (if applicable) is preferred,
followed by the primary output, if available, otherwise the server may
choose any output upon which the window is centered.
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.
Composite managers may listen to this event to choose a more favorable color
space/encoding for rendering into the target window.
DPCCompositorChangeNotify
requester: WINDOW window requesting notification
override_list: LISTofOVERRIDE updated outputs and 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.
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.
If a new output is added to the screen, the server will initialize the
compositor capabilities for the new output to be identical to those of
existing outputs (or empty if none existed prior). If a composite manager
has overridden the compositor capabilities, the scores will be initialized
to 0, otherwise the server may choose. It will then generate a
DPCCompositorChangeNotify event after the associated RROutputChangeNotify
event.
Applications should listen to this event and change which color
space/encoding they are using for rendering if their current selection is no
longer supported or preferred.
Composite managers may listen to this event in order to override scores of
new outputs with more accurate selections.
DPCWindowCompositorChangeNotify
requester: WINDOW window requesting notification
output: OUTPUT output upon which the window is centered
colorspace_list: LISTofCOLORSPACEPRIORITY updated compositor capabilities
This event is generated whenever the output upon which the requesting window
is centered, or the capabilities of its associated compositor, changes. In
the case of a tie, the previously chosen output (if applicable) is
preferred, followed by the primary output, if available, otherwise the
server may choose any output upon which the window is centered.
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.
Applications may listen to this event as an alternative to the more general
DPCCompositorChangeNotify, and change which color space/encoding they are
using for rendering if their current selection is no longer supported or
preferred.
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.
If the Damage event is present, only future contents as indicated by
DamageNotify events should be interpreted with the new color space/encoding.
Composite managers should 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 inaccurate
composition.
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 FLOAT32 gamma
COLORSPACEPRIORITY
8 COLORSPACE
4 CARD32 score
4 unused
OVERRIDE
4 OUTPUT output
4 c number of COLORSPACEPRIORITYs in list
8 unused
16c LISTofCOLORSPACEPRIORITY colorspace_list
DPCSELECTMASK
0x0001 DPCDisplayChangeNotifyMask
0x0002 DPCWindowDisplayChangeNotifyMask
0x0004 DPCCompositorChangeNotifyMask
0x0008 DPCWindowCompositorChangeNotifyMask
0x0010 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 unused
4 4+4c+4o(c+1) request length
4 o number of OVERRIDEs in list
4 c number of COLORSPACEPRIORITYs/OVERRIDE
16c unused
o(16(c+1)) LISTofOVERRIDE override_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
DPCSetNextPresentColorspace
1 CARD8 opcode
1 10 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
DPCWindowDisplayChangeNotify
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
DPCCompositorChangeNotify
1 35 (GenericEvent) type
1 DPC extension
2 CARD16 sequence number
4 MAX(0,4(c-1))+4o(c+1) length
2 2 evtype
2 unused
4 WINDOW requester
4 o number of OVERRIDEs in list
4 c number of COLORSPACEPRIORITYs/OVERRIDE
8+MAX(0,16(c-1)) unused
o(16(c+1)) LISTofOVERRIDE override_list
DPCWindowCompositorChangeNotify
1 35 (GenericEvent) type
1 DPC extension
2 CARD16 sequence number
4 4c length
2 3 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 4 evtype
2 unused
4 WINDOW requester
4 COLORSPACE colorspace
12 unused
9. Issues
Should SMPTE 2086 metadata be included, e.g. color primaries, white point, and
luminance range of the mastering display, in order to tune tonemapping at the
target HDR10 display? An additional request could be added to optionally
associate such metadata with a window.
See also:
https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_surface_SMPTE2086_metadata.txt
https://raw.githubusercontent.com/KhronosGroup/Vulkan-Docs/1.0/doc/specs/vulkan/appendices/VK_EXT_hdr_metadata.txt
Similarly, formats such as Dolby Vision and HDR10+, neither of which are
currently included in this spec, require SMPTE 2094 dynamic metadata, which can
change from frame to frame. This could be updated with a new request similar to
DPCSetNextPresentColorspace.
Adding SMPTE 2094 to this extension would require synchronizing direct rendering
with X protocol, which is undesirable. Likewise, SMPTE 2086 handles metadata
that does not directly pertain to the stored format of the pixel data, so it may
be outside the scope of this extension. Perhaps there should be a GLX extension
to mirror the EGL and Vulkan extensions?
In the case of a mismatch between capabilities and a color space/encoding being
used, there is a suggestion to restrict the image presented on the screen to the
precision of the associated core visual, but the mechanism with which this could
be done is not clear.
10. References
[DAMAGE]
Packard, Keith and Eric Anholt, "The DAMAGE Extension", 2007-01-08,
https://cgit.freedesktop.org/xorg/proto/damageproto/plain/damageproto.txt
[RANDR]
Gettys, Jim and Keith Packard, "The X Resize, Rotate and Reflect Extension",
2009-10-05,
https://cgit.freedesktop.org/xorg/proto/renderproto/tree/renderproto.txt
[COMPOSITE]
Packard, Keith and Deron Johnson, "Composite Extension", 2007-07-03,
https://cgit.freedesktop.org/xorg/proto/compositeproto/plain/compositeproto.txt
[PRESENT]
Packard, Keith, "The Present Extension", 2013-06-06,
https://cgit.freedesktop.org/xorg/proto/presentproto/plain/presentproto.txt
More information about the xorg-devel
mailing list