Here is an updated version of the spec based on the recent feedback, also including a couple new issues that came up.
Diff is followed by full text. Thanks, Alex diff --git a/deepcolorproto.txt b/deepcolorproto.txt index 7406762..87fbf2d 100644 --- a/deepcolorproto.txt +++ b/deepcolorproto.txt @@ -44,10 +44,16 @@ Andy Ritger, NVIDIA Corporation <[email protected]> 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. +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. @@ -55,9 +61,9 @@ Events are delivered via the Generic Event Extension. 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. +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 @@ -66,8 +72,10 @@ 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 +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. @@ -85,6 +93,10 @@ 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 @@ -115,6 +127,11 @@ COLORSPACETYPE { Undefined 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. @@ -163,12 +180,13 @@ COLORSPACETYPE { Undefined an FP16 pixel format. COLORSPACE { type: COLORSPACETYPE - gamma: FIXED } + 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. If 'type' is a color space/encoding type that does not require a - gamma value, 'gamma' is undefined. + 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 } @@ -210,21 +228,19 @@ The name of this extension is "DEEP-COLOR". 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. + change. DPCDisplayChangeNotify events 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 may also be sent when - this request executes if the compositor capabilities have changed since the - client connected, to avoid race conditions. + the screen changes. DPCCompositorChangeNotify events 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 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. + requested window changes. DPCWindowChangeNotify events will be sent when + this request executes to avoid potential race conditions when a client + connects. DPCGetVisualInfo @@ -257,8 +273,9 @@ The name of this extension is "DEEP-COLOR". 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. + 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 @@ -284,9 +301,9 @@ The name of this extension is "DEEP-COLOR". 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. + 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 @@ -308,9 +325,9 @@ The name of this extension is "DEEP-COLOR". 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 + 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. + window, or the contents may not be composited accurately. DPCGetWindowCompositorCapabilities @@ -334,9 +351,9 @@ The name of this extension is "DEEP-COLOR". 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 + 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. + window, or the contents may not be composited accurately. DPCOverrideCompositorCapabilities @@ -344,26 +361,30 @@ The name of this extension is "DEEP-COLOR". output: OUTPUT colorspace_list: LISTofCOLORSPACEPRIORITY - Errors: Output + Errors: Output, Match - 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. + Used by a composite manager to override the set of possible color + spaces/encodings and associated scores for composition for a given output. - 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. + 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. - 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. + 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 associated scores may vary from output to output. + 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. DPCGetWindowColorspace @@ -390,21 +411,58 @@ The name of this extension is "DEEP-COLOR". 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. + 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 must be supported by the display. Rendering using - options not supported by the display will result in undefined graphical - behavior. + 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 call. + space/encoding is changed by this request. 7. Extension Events @@ -447,10 +505,21 @@ The name of this extension is "DEEP-COLOR". 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. + 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. They may choose a more favorable color space/encoding even + if their current selection is still supported. + + Composite managers may listen to this event in order to override scores of + new outputs with more accurate selections. DPCWindowChangeNotify @@ -462,10 +531,13 @@ The name of this extension is "DEEP-COLOR". 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 + 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 undefined - graphical behavior. + in response to DPCWindowChangeNotify events could result in inaccurate + composition. 8. Protocol Encoding @@ -506,7 +578,7 @@ encoding document. COLORSPACE 4 COLORSPACETYPE - 4 FIXED gamma + 4 FLOAT32 gamma COLORSPACEPRIORITY @@ -666,6 +738,15 @@ encoding document. 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. @@ -714,27 +795,40 @@ DPC is the major opcode for the extension, as returned by XQueryExtension. 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. +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. + +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, - http://cgit.freedesktop.org/xorg/proto/renderproto/tree/renderproto.txt + https://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 + https://cgit.freedesktop.org/xorg/proto/compositeproto/plain/compositeproto.txt -[RENDER] - Packard, Keith, "The X Rendering Extension", 2009-07-15, - http://cgit.freedesktop.org/xorg/proto/renderproto/tree/renderproto.txt +[PRESENT] + Packard, Keith, "The Present Extension", 2013-06-06, + https://cgit.freedesktop.org/xorg/proto/presentproto/plain/presentproto.txt ----- DeepColor Extension Version X.X 2017-XX-XX Alex Goins [email protected] 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 <[email protected]> Gary Demos, <[email protected]> Adam Jackson, Red Hat, Inc. <[email protected]> James Jones, NVIDIA Corporation <[email protected]> Robert Morell, NVIDIA Corporation <[email protected]> Keith Packard, Hewlett-Packard Company <[email protected]> Aaron Plattner, NVIDIA Corporation <[email protected]> Andy Ritger, NVIDIA Corporation <[email protected]> 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. 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 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 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. 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. 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 output: OUTPUT colorspace_list: LISTofCOLORSPACEPRIORITY 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. 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. 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. 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. 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 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. 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. They may choose a more favorable color space/encoding even if their current selection is still supported. Composite managers may listen to this event in order to override scores of new outputs with more accurate selections. 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 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 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 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 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. 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 On Thu, 19 Oct 2017, Alex Goins wrote: > On Sun, 15 Oct 2017, Keith Packard wrote: > > > Alex Goins <[email protected]> writes: > > > > > Thanks, Adam. > > > > > > Here's an updated version of the spec: > > > > This is looking very good. I don't have any architectural concerns at > > this point, just some editorial comments. > > Thanks, that's good to hear. > > > > Rendering to DeepColor windows using the core protocol, however, is > > > loosely > > > defined. > > > > It seems to be actually fairly well defined to me. If core pixel values > > could be 'round-tripped' through the deep storage, then core rendering > > would be exact. That seems pretty simple with the UINT* formats when > > used with a non-linear colorspace -- just use an identity mapping. > > Core rendering would be exact relative to core operations e.g. GetImage, but > relative to the HDR format it would be more loosely defined. Probably just a > matter of wording. > > Using the identity mapping for UINT* formats would work, as long as we don't > care about an accurate representation of the SDR content when interpreted by > HDR > consumers. With a more accurate transfer function, SDR content could look > correct even for HDR consumers. The spec leaves that up to the server, > however, > hence it being "loosely defined." > > > For a linear color space using FP format, I wonder if you could define a > > function that would result in reliably transferring 256 levels in and > > out of each primary? > > I don't see why not, but the same points about HDR consumers apply. > > > The principle reason I ask is that if pixel values can be reliably > > stored in deep visuals, then the existing testing infrastructure can be > > used to validate the implementation. > > Good point. The only part that really matters there is that there is a fixed > 1:1 > mapping between the SDR pixel values and a set of HDR pixel values. As to > whether the pixel values correspond to similar shades in both formats > shouldn't > matter to core operations, but would to the HDR display. > > The point about the 1:1 mapping between pixel values isn't very explicit in > the > current wording of the spec, but could be included as an explicit contraint on > the server's transfer function. > > I could see that complicating things slightly for implementations that want to > preserve accurate color both when displayed as HDR and when interpreted as > SDR, > but it shouldn't be unachievable, especially since the former case would only > be > about looking correct, rather than perfect accuracy. > > > > 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. > > > > I think you should define "OETF" in the spec; most people reading this > > will not know where to start looking for a definition. > > Yes, I can do that. > > > > COLORSPACE { type: COLORSPACETYPE > > > gamma: FIXED } > > > > Could you just use a FLOAT here? glx uses IEEE floats all over its > > protocol, so it wouldn't be a new type on the wire. I'm a bit sorry to > > not have used floats for Render; that was done when many smaller > > embedded systems still lacked floating point hardware and we were > > concerned about the performance implications of floats in the rendering > > path. For this extension, there's no performance impact here, and using > > a real float would be better. Heck, if you like, use a 64-bit IEEE float. > > Yeah, I chose FIXED because I was using Render as a reference and wasn't aware > of the possibility of using floats in protocol. I agree that that is better. > > > > DPCSelectInput > > > > > > window: WINDOW > > > enable: SETofDPCSELECTMASK > > > > > > Errors: Window, Value > > > > Either this request should always deliver an event or never deliver an > > event. Having it 'sometimes' deliver events seems messy. I'd suggest > > just having it always deliver one of each of the events selected; it's > > easy to implement and, as you say, avoids race conditions when the > > developer combines this with the query in the wrong order. That's > > actually a nice cleanup compared with similar functionality in existing > > functions. > > Fair enough. > > > > A composite manager must use a color space/encoding supported by the > > > display(s) when compositing into the target window. > > > > What error is returned if this isn't done? And wouldn't a regular > > application, running in non-composited mode, also have the same > > requirement? After all, a compositing manager is just a regular client > > drawing to a regular window. > > The wording should probably be changed to "should." As written, there is no > error if a composite manager chooses something not supported by the display, > just no expectation that the results will be displayed accurately. The > capabilities of the display aren't allowed to change, only the preferences > (the > expectation being that the server will convert internally anything that > doesn't > match perfectly to the mode on a given display), so there's no excuse for a > compositor to choose an option that the display doesn't support. > > An application, running in non-composited mode, does have the same > requirement. > However, in this case, the server is responsible for "compositing." The > "compositor" properties don't apply only to composite managers, they also > apply > to the server's capabilities when no compositor is running. > > The reason for separating "compositor" and "display" capabilities is to solve > the problem of a composite manager overriding the "compositor" capabilities > and > then having no visibility into what the server supports or prefers. > > If an application is not a composite manager, i.e. does not redirect the root > window hierarchy and does not override compositor capabilities, it would look > at > the compositor capabilities regardless of whether or not a composite manager > is > running. An application shouldn't have to care if a composite manager is > running > or not, it just checks the "compositor" capabilities with the understanding > that > they are subject to change. Whether that's because the in-server > compositor/composite manager changed capabilities/preferences, or because a > composite manager started where there wasn't one before, is irrelevant to the > application. > > > > DPCOverrideCompositorCapabilities > > > > > 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. > > > > I think this means the compositing manager is required to emit one of > > these requests for each output? If so, why not simply place all of those > > in a single request so that we can verify that the compositing manager > > did the right thing? > > The scores associated with the color spaces could vary between outputs (say, > if > the outputs are driving different HDR modes and the compositor wants to > indicate > to applications that a certain output prefers a certain input, since > applications don't pay attention to the display capabilities), and > representing > that in one request would require a variable length list of variable length > lists, screwing up the encoding. > > I actually just noticed that there is an artifact from when I originally wrote > this request as you described, the last paragraph referencing 'overrides', > which > was originally a list of capabilities for each output. I must have missed > that. > > > What happens when another output is added to the screen? > > Good question. I suppose that the composite manager (if applicable, otherwise > it's all handled by the server anyway), would have to listen for > RROutputChangeNotify and then use DPCOverrideCompositorCapabilities on that > display, but that would still result in a transient state in between. > > Maybe the server could initialize the capabilities to a list of colorspaces > identical to the other outputs (since they are required to be identical other > than score), with all of the scores set to 0 until the composite manager > overrides it. > > In any case the new output would be expected to have the same capabilities of > the existing outputs, based on existing constraints. The capabilities, after > all, have more to do with what the composite manager understands as input than > anything specific to particular outputs. The reasoning for different > capabilities per output is simply so that an application can intelligently > pick > an option based on the preferences of each output and the current location of > the 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. > > > > I'd really rather this be 'should' and not 'must'. Given that we have > > reasonable well-defined behaviour for conversion to core pixel values, > > any colorspace not directly supported by the compositing manager can be > > supported using core/render operations, leaving clients still functional > > even with a mismatch between their colorspace and the compositing > > manager colorspace. > > Given prior discussion, I agree. "Must" should probably be something enforced > by the protocol, as this is not. Applications "should" use options supported > by > the compositor just as composite managers "should" use options supported by > the > display, since there's no expectation of accuracy otherwise. > > Since color space/encoding as this spec is concerned is orthogonal to actual > storage format, choosing incorrectly should never be catastrophic, just > probably > won't look right (albeit probably still recognizable). > > > In its current form, this places a higher burden on applications than > > compositing managers here -- they *must* support whatever colorspace the > > compositing manager offers, while the compositing manager is free to > > support only those it likes. > > Well, it's kind of a given that the producer must produce output that the > consumer can take as input, in all cases, with the server down stream from the > composite manager (if applicable) and the composite manager down stream from > the > applications. > > I agree that the requirement should be loosened from a protocol perspective, > all > of this should just be about helping each stage of the pipeline negotiate a > desirable configuration with the later stage of the pipeline, and indicating > their configuration so their output can be consumed accuracy. > > The exception is pixel format, which has to be explicit, but the lack of > flexibility there means it isn't so complex. > > > > 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. > > > > I'm not happy with 'undefined' behaviour here. We've got three moving > > pieces here (display, compositor, app) and things only work right when > > they all follow the rules, and those rules are subject to arbitrary > > change as you start/stop compositing managers and connect/disconnect > > displays. > > > > I think a simple requirement is that the application be allowed to > > choose any colorspace it likes and that, at worst, the image presented > > on the screen will have been restricted to the associated core visual > > precision. That's well defined by the spec and will mean that > > incompatibilities between applications, compositing manager and display > > will only result in lower-fidelity images, not 'undefined' results. > > That is something to consider, but how would you do that? Restricting to SDR > is > easy when we're only talking about core rendering being read by core > operations, > but what about output produced by HDR graphics APIs? > > How does the server know how to restrict the output of the composite manager > to > SDR if it doesn't understand the format the output is in? The same issue > occurs > between the compositor and the application. > > Later stages in the pipeline have no way to force earlier stages to put a > certain format of pixels into their buffers, they can only make it clear which > formats are supported. > > They could make a best effort, but that's really no better than "undefined." > > > > 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. > > > > Yup. Should work fine. This should be done using a separate request so > > that applications can still set the colorspace without using > > Present. Essentially, the application would do > > > > SetNextPresentColorspace > > PresentPixmap > > > > and the colorspace seen by the compositor when it receives the > > associated damage will be the new one. Hrm. It will receive that in an > > event, presumably directly before the Damage event. The compositor would > > be wise to look for a damage event when it receives the new colorspace > > information, or perhaps it could infer that only future contents as > > indicated by Damage events should be interpreted in the new colorspace? > > That makes sense. > > Seems it could be handled either way, the understanding just being that all > future damage after receiving a DPCWindowChangeNotify event would be in the > new > color space. Not a bad convention to go by even without use of the Present > extension, it just wouldn't be guaranteed without it. > > Thanks, > Alex > > > > > -- > > -keith > > >
_______________________________________________ [email protected]: X.Org development Archives: http://lists.x.org/archives/xorg-devel Info: https://lists.x.org/mailman/listinfo/xorg-devel
