[RFC PATCH v2 1/1] Adding color calibration protocol
Erwin Burema
e.burema at gmail.com
Tue May 21 17:32:16 UTC 2019
---
.../wp_wayland_calibration.xml | 247 ++++++++++++++++++
1 file changed, 247 insertions(+)
create mode 100644 unstable/color_calibration/wp_wayland_calibration.xml
diff --git a/unstable/color_calibration/wp_wayland_calibration.xml b/unstable/color_calibration/wp_wayland_calibration.xml
new file mode 100644
index 0000000..dbeeb42
--- /dev/null
+++ b/unstable/color_calibration/wp_wayland_calibration.xml
@@ -0,0 +1,247 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="wp_calibrate__profile_unstable_v1">
+
+ <copyright>
+ Copyright © 2019 Erwin Burema
+
+ 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.
+ </copyright>
+
+ <interface name="zwp_calibration_manager_v1" version="1">
+ <description summary="Manager object for profiling/calibration of displays">
+ With this interface a compositor can announce calibration/profiling
+ support so a software can calibrate the display. This protocol should
+ be priviliged.
+
+ Currently this is just a sketch for a proposal
+
+ THIS INTERFACE IS EXPERIMENTAL!
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="destroy the calibration manager">
+ Destroy the calibration manager
+ </description>
+ </request>
+
+ <request name="cm_profile">
+ <description summary="Request to calibrate/profile a given output">
+ A program sends this request to a compositor to calibrate/profile a
+ given output, it will use the provided surface to display the
+ profile/calibration data and potentially user assistance information.
+
+ A compositor can deny this request (for example when the output is in
+ use by another full screen application or when in an HDR state that
+ can't be calibrated/profiled), in this case it should give an error as
+ defined in the exception enum and the first event of the calibration
+ object must be a cancled event.
+ </description>
+ <arg name="id" type="new_id" interface="zwp_output_cal_v1" />
+ <arg name="surface" type="object" interface="wl_surface" />
+ <arg name="output" type="object" interface="wl_output" />
+ </request>
+
+ <enum name="exceptions">
+ <entry name="not_supported" value="0"
+ summary="Output doesn't suport calibration/profiling" />
+ <entry name="not_saved" value="1"
+ summary="Afer calibration/profiling no profile or video card lut was saved" />
+ <entry name="user_cancled" value="3"
+ summary="User cancled calibration"/>
+ <entry name="output_in_use" value="4"
+ summary="Output in use by other callibration and/or fullscreen application" />
+ </enum>
+
+ <event name="exception">
+ <description
+ summary="A runtime error happened see exceptions enum for more info"/>
+ <arg name="error" type="uint" enum="exceptions" />
+ <arg name="reason" type="string"
+ summary="Short human readable description of error" />
+ </event>
+
+ </interface>
+
+ <interface name="zwp_output_cal_v1" version="1">
+ <description summary="Main calibration profiling interface">
+ This is the interface that the calibrator/profiler will use to actually
+ calibrate/profile a screen. The buffer of the attached surface will be
+ displayed above everything else in full screen and the compositor should
+ disable any DPMS/screensaver. To make sure the compositor knows where it
+ can't draw the callibration application should use
+ wl_surface::set_opaque_region
+ Locking is still allowed so long as the Lock screen is not displayed on
+ top of the calibration surface inside the opaque region(s).
+
+ The surface will be displayed as if it was in the display color space. So
+ the compositor CMM should at most do an identy transform or blit the buffer
+ as directly to the screen as possible (depending on how the compositor
+ normally operates with surfaces in the display color space)
+
+ The compositor is allowed to stop the process at any time by sending a
+ cancled event. In this case the surface will be unmapped any calibration
+ done will be undone and no further events will be sent nor any request
+ honered. The application should destroy this interface in that case.
+ </description>
+
+ <enum name="bitdepth">
+ <entry name="NA" value="0"
+ summary="Not used (only valid for Gamma_in/out)" />
+ <entry name="8bit" value="1" summary="8 Bit display" />
+ <entry name="10bit" value="2" summary="10 Bit display" />
+ <entry name="12bit" value="3" summary="12 Bit display" />
+ <entry name="14bit" value="4" summary="14 Bit display" />
+ </enum>
+
+ <event name="display_config">
+ <description summary="Event send to inform application of display depth">
+ This event will be fired on creation of an wp_output_cal object;
+ providing the calibration program the nescary information for
+ calibrating/profiling the screen.
+
+ NOTE: If the compositor is using a shader for the LUT/gamma table it is
+ free to set anything for the Gamma_in/out. If using the video card LUT
+ it should provide the size of that LUT.
+
+ In some cases LUT/gamma tables are not provided (e.g. some display HW
+ has only 1 shared over all displays so only the main display can be
+ calibrated)
+
+ The client must obey the size exactly on the next commit with a wl_buffer.
+ </description>
+ <arg name="depth" type="uint" enum="bitdepth"
+ summary="Current display bit depth" />
+ <arg name="Gamma_in" type="uint" enum="bitdepth"
+ summary="Input size of LUT/Gamma table" />
+ <arg name="Gamma_out" type="uint" enum="bitdepth"
+ summary="Output size of LUT/Gamma table" />
+ <arg name="width" type="uint" summary="widht of output in pixels" />
+ <arg name="height" type="uint" summary="height of output in pixels" />
+ </event>
+
+ <event name="cancled">
+ <description summary="Event sent in case calibration is cancled/aborted">
+ This events denotes that the calibration is aborted/cancled or (in the
+ case this is the first event) the calibration can't start.
+ </description>
+ </event>
+
+ <request name="id_lut">
+ <description
+ summary="Request to create an identy LUT of right size for this output"/>
+ <arg name="lut" type="new_id" interface="zwp_cm_lut"
+ summary="object holding the id LUT" />
+ </request>
+
+
+ <reqest name="get_lut">
+ <description summary="Get the current LUT">
+ With this request a program can gets a copy of the current loaded LUT
+ </description>
+ <arg name="lut" type="new_id" interface="zwp_cm_lut"
+ summary="Object describing a LUT"/>
+ </request>
+
+ <request name="load_lut">
+ <description summary="Request to load a new LUT">
+ To setup a new LUT, this is traditionally loaded in either the Video
+ card LUT/Gamma table. But a compositor is free to use a shader instead.
+
+ This request will only be honered if the Gamma_in/out are actually
+ provided.
+ </description>
+ <arg name="lut" type="object" interface="zwp_cm_lut"
+ summary="Object providing a LUT" />
+ <arg name="callback" type="new_id" interface="wl_callback"
+ summary="callback that will fire when callibration curve is loaded" />
+ </request>
+
+ <request name="load_profile">
+ <description summary="Load a given profile including VCGT">
+ USed to load a given ICC profile a compositor should also apply the VCGT
+ if provided, traditionally this is done wiht the video card LUT/Gamma
+ table but a compositor is free to do it in a shader so long as it is
+ done after any of the CMM transforms (as the last step before pushing
+ to the screen).
+
+ If this interface is destroyed without saving compositor should
+ restore previous settings
+ </description>
+ <arg name="profile" type="fd"
+ summary="file descriptor to ICC profile"/>
+ <arg name="callback" type="new_id" interface="wl_callback"
+ summary="callback that will fire when profile is loaded" />
+ </request>
+
+ <request name="save" type="destructor">
+ <decsription summary="Last profile loaded should be saved">
+ Send this to save the last profile loaded, compositor is allowed to
+ check this profile and deny the reqest (see error enum in manager interface).
+ irregardless of if profile gets saved or not this will destroy this interface.
+ If not saved compositor should restore previous settings.
+ </description>
+ </reqest>
+
+ <request name="desstroy" type="destructor">
+ <description summary="Destroy object without saving" />
+ </request>
+
+ </interface>
+
+ <interface name="zwp_cm_lut" version="1">
+ <description summary="Object for holding calibration LUT data">
+ The compositor will create an ammount of shared memory that will hold the
+ LUT data. It will be in a format of an array of unsigned 16 bit integers
+ (little endian), with a lenght of 3x the LUT input size. The red, green and
+ blue information will be stored interlaced (so R1,G1,B1,R2,G2,B2,etc).
+
+ The 16bit integers will be scaled to the output LUT size, effectively making
+ the output size determine the step size of the 16bit integers.
+
+ In case there is no LUT the no_LUT event will be provided. The client is
+ then supposed to destroy this object.
+ </description>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the LUT">
+ Destroy the LUT and any associated data
+ </description>
+ </request>
+
+ <event name="no_LUT" />
+
+ <event name="LUT_data">
+ <description summary="fd to shared memory">
+ This event will be fired on creating a zwp_cm_lute and will provide a
+ file descriptor the the shared memory provided for storing a LUT
+ </description>
+ <arg name="shm" type="fd" />
+ </event>
+
+ <request name="set_new_LUT">
+ <description summary="set a new LUT">
+ Provide a new LUT in described format
+ </description>
+ <arg name="shm" type="fd" />
+ </request>
+
+ </interface>
+
+</protocol>
--
2.21.0
More information about the wayland-devel
mailing list