Sketch of a set of Wayland Color Management protocols. 21st May 2019 Author: Graeme Gill. -------------------------------------------------------- Wayland protocol information: Language/protocol: Object = interface global namespace for objects/interfaces. request(s) to server, sent to an object event(s) from server, emitted by an object enum(s) int, uint, bitfield no booleans enums can't be interfaces State broadcast on connection Events broadcast on state change (No query of state possible) Arguments: int, uint The value is the 32-bit value of the signed/unsigned int. fixed Signed 24.8 decimal numbers. It is a signed decimal type which offers a sign bit, 23 bits of integer precision and 8 bits of decimal precision. This is exposed as an opaque struct with conversion helpers to and from double and int on the C API side. string Starts with an unsigned 32-bit length, followed by the string contents, including terminating null byte, then padding to a 32-bit boundary. object 32-bit object ID. new_id The 32-bit object ID. On requests, the client decides the ID. The only events with new_id are advertisements of globals, and the server will use IDs below 0x10000. array Starts with 32-bit array size in bytes, followed by the array contents verbatim, and finally padding to a 32-bit boundary. fd The file descriptor is not stored in the message buffer, but in the ancillary data of the UNIX domain socket message (msg_control). Examples: See list of files in d:/src/wayland/xml Design - object lifetime: Create client object using new_id argument in request. Create server object using new_id argument in event. This requires care. Object creation "never fails". i.e. object can be used immediately after creation. Objects are usually destroyed by server on client wl_foobar_destroy() request. Objects may be destroyed in server event. This requires great care. (wl_callback example) Server created objects have race conditions in destruction. A way to prevent races is to add: A "stop" request that asks the compositor to stop sending events and destroy the object A "finished" event that notifies the client that the compositor has destroyed the object. The client will then be able to release resources. Errors should be an error enum per interface ============================================================== Color Management protocols. ----------------------------------------------------------------- Copyright 2019 Graeme W. Gill Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. The purpose of the protocol is to allow client applications to manage color of all their output. Color management may operate in one of four ways: 1) No color management. Either the Wayland server doesn't support the color management extensions, or the clients wl_output has no output color profile configured. Client output will be interpreted as being in the outputs native color space for all outputs and no color transformations will be performed. 2) Server managed default color. If the server is configured to have a color profile for an output and also has a default source color space set and a client does not tag their wl_buffers with a source colorspace, then they will have color managed by the server and their output will be interpretted as being in the default source colorspace, and will be rendered using the default intent if it is set. 3) Server managed client color. If the server is configured to have a color profile for an output and the client tags its wl_buffers with either a globaly avilable color space or a client specific color space, then the client will have color managed by the server and their output will be interpretted as being in the specified source colorspace using either the default or the rendering intent they specify for the wl_surface. 4) Client managed color. The client is able to track the current wl_output a wl_serface is mapped to using the wl_surface.enter/leave events, and in the situation that a surface is mapped to more than one output it can prioritise the outputs by consulting the color output priority list. It can download an outputs color profile and then perform it's own color conversion to the wl_output colorspace, and tag the resulting wl_buffer contents with that wl_outputs color profile. Server rendering to that wl_output will perform no color transformation, while server rendering of that buffer to other wl_outputs will transform from the tagged color space to that output using the default rendering intent. When a client creates a color_manager object, the color_manager object will emit an output_profile event for each wl_output, notifiying the client of its color space. An output that either has no color space set or has color management disabled will return a null color_profile_id. An event will also be issued if the output profile has been updated, or its fidelity order has been changed. If an application has set an abstract profile for this output using the output_color_modification protocol, the abstract_id will be set. A client implementing its own color management should implement this as part of its color processing, unless it is contrary to the purpose of the application or application or image. An application may wish to use the presense of a non null abstract profile to warn the user that there is a display wide color modification in force. hdr_max is the HDR maximum white light level in cd/m^2, and has a value of 0 if not an HDR colorspace. hdr_diffuse is the notional HDR diffuse white light level in cd/m^2, and has a value of 0 if not an HDR colorspace. The fidelity order is smallest to largest integer corresponding to highest to lowest wl_output priority. The integers are arbitrary and need not be consecutive. If more than one output has the same priority value, then the priority is indeterminate. When a client creates a color_manager object, the color_manager object will emit a standard_profile event for each available global color_profile_id, notifiying the client of its availability. Globally available ICC profiles. .... The profile has been uploaded and the fd is no longer needed The profile may be an output profile, a standard profile, a client private profile, or null. If a null profile id is set, then the buffer will be interpretted as being in the wl_outputs color space for all outputs and no color transform will be performed. If the buffer is tagged with an wl_outputs color space, then the buffer will be interpretted as being in that wl_outputs color space and no color transform will be performed for that output. If an wl_output profile_id is no longer valid, then the compositor will issue an output_profile event before returning an invalid_color_profile_tag error event. (This may occur as the result of a race if an outputs profile is updated.) It is an error to set a profile that isn't capable of conversion from buffer device values to PCS values. hdr_max is the HDR maximum white light level in cd/m^2, and has a value of 0 if not an HDR colorspace. hdr_diffuse is the notional HDR diffuse white light level in cd/m^2, and has a value of 0 if not an HDR colorspace. Set the color intent handling for a surface for the next commit of a buffer to that surface. This overrides the default. This is a doubly buffered attribute. ICC format device or profile with 3 channels. It may be icSigInputClass, icSigDisplayClass, icSigOutputClass or icSigColorSpaceClass. It is an error to attempt to use a profile for a conversion direction that it doesn't support. Download a output or standard or client private or abstract ICC device profile. If an wl_output profile_id or abstract_id is invalid, then the compositor will issue an output_profile update event before returning an invalid_color_profile_tag error event. (This may occur as the result of a race if an outputs display profile or abstract profile is updated.) The profile has been downloaded and the fd is no longer needed These errors are global and can be emitted in response to any server request. ============================================================================== ============================================================================== Copyright 2019 Graeme W. Gill Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Wayland server color management The server should only expose this protocol to color management and system configuration applications. The purpose of this protocol is to allow system configuration and color management tools to configure server color management, and color management tools to calibrate, profile and verify color behaviour of displays. Upload an ICC profile and suplemental HDR information for the given output. This enables color management for that output and replaces any previous wl_output profile. This is a persistent configuration. Any previous color_profile_id will become invalid or may be re-used when no wl_buffers are tagged with it. This will trigger an output_profile event. It is an error to upload a profile that isn't capable of conversion from PCS to device values. Any 'vcgt' tag per channel curves in the profile are implemented in a manner equivalent to the capabilities of the CRTC hardware per channel lookup tables. If the profile contains no 'vcgt' tag, then the CRTC hardware will be set to linear. The profile has been uploaded and the fd is no longer needed If the server has a means of determining the outputs color response such as EDID information, then the default state should be an ICC display profile created from that information. If no color behavior information is available, then the output profile will be set to null. This is a persistent configuration. The output profile will be set to null. This is a persistent configuration. This information is used by clients that manage their own color. The fidelity order is smallest to largest integer corresponding to highest to lowest wl_output priority. The integers are arbitrary and need not be consecutive. If more than one output has the same priority value, then the priority is indeterminate. This is a persistent configuration. ### need to get 'vcgt' bit depths for a given wl_output ### This is used by a color management application to temporarily disable color calibration during calibration measurements, set color values at a higher precision than the frame buffer may allow, and to temporarily configure a specific calibration during color profiling. Upload an ICC profile and use just it's 'vcgt' tag to override the 'vcgt' setting on the wl_output. This replaces any previously set temporary 'vcgt' tag set by this client. If the client disconnects, then the 'vcgt' state is restored to its original state :- ie. how it is set by the current wl_output profile, or linear if there is no wl_output profile. It is an error to attempt to set a 'vcgt' override when some other client is currently overriding the wl_outputs 'vcgt'. It is an error to upload a profile that doesn't contain a 'vcgt' tag. The profile must have a valid set of ICC tags, but all other tags other than the 'vcgt' will be ignored. The profile has been uploaded and the fd is no longer needed and the temporary 'vcgt' is now affecting display output, or the temporary 'vcgt' has been cleared and the 'vcgt' state has been restored to its original state. ### should this be in the style of wl_shell instead ? see also fullscreen-shell-unstable-v1.xml ### i.e. regard this as an additional surface role ? It is an error to make a surface a test_patch_surface if there is a lock screen in place. If a test patch surface is able to be displayed, then it is displayed above every other surface including the cursor. The surface is opaque. No output color modification abstract profile is to be applied when color managing this surface. No "power saver" or "screen saver" is to distrupt the content on this surface. !! see zwp_idle_inhibit_manager_v1 in idle-inhibit-unstable-v1.xml ### setting x,y should be request on role object ? or do we just create a new surface if we want to change size & position ? ### ### this is incomplete ### This interface is exposed as a global singleton. This interface is implemented by servers that provide server_color_management. This request gives the wl_surface the role of a color test patch surface. The server regards following cases as protocol errors and disconnects the client. - wl_surface already has an nother role. ### this is incomplete ### The profile may be an output profile or a standard profile or null. If the profile is nulll or the profile is the same as a that of the wl_output being rendered to, then buffers will be interpretted as being in the wl_outputs color space and no color transform will be performed for that output. This is a persistent configuration. If an output profile_id is used and becomes invalid, then the compositor will issue an output_profile event before returning an invalid_color_profile_tag error event. (This may occur as the result of a race if an outputs profile is updated.) It is an error to set a profile that isn't capable of conversion from buffer device values to PCS values. The intent used for color conversions will be relative colorimetric with BPC (?) hdr_max is the HDR maximum white light level in cd/m^2, and has a value of 0 if not an HDR colorspace. hdr_diffuse is the notional HDR diffuse white light level in cd/m^2, and has a value of 0 if not an HDR colorspace. ============================================================================== ============================================================================== Copyright 2019 Graeme W. Gill Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. To support applications such as "red shift" etc. in a way that works in concert with color management, and makes the desired transformations display behavior independent. The server should only expose this protocol to applications whoes purpose is to provide such display wide color modifications. Upload an abstract ICC profile for the given output. This will be applied to the PCS in all color management transformations for that output. This will replace any previous abstract profile for that output. The abstract profile will be deleted when the client disconnect. The abstract transformation should assume relative colorimetric intent with BPC is being used, so that the PCS luminance range is from 0,0,0 to PCS white. The compositor may apply luminance scaling to the destination PCS values to ensure that the source PCS white remains in gamut. The abstract profile has been uploaded and the fd is no longer needed