===============================================================
Preliminary sketch of a set of Wayland Color Management protocols.
21st May 2019
-----------------------------------------------------------------

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="client_color_management_v1">

  <copyright>
    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.
  </copyright>

  <description summary="client color management protocol"">
    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's 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.
  </description>

  <interface name="client_color_manager" version="1">
  
    <!-- notify client of wl_output color profiles -->
    <event name="output_profile">
      <description summary="wl_output color profile">
        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.
      </description>
      <arg name="output_id" type="object" summary="output"/>
      <arg name="profile_id" type="object" allow-null="true" summary="associated color profile"/>
      <arg name="abstract_id" type="object" allow-null="true" summary="associated abstract color profile"/>
        <arg name="hdr_max" type="fixed" summary="hdr max brightness"/>
        <arg name="hdr_diffuse" type="fixed" summary="hdr diffuse white"/>
        <arg name="fidelity_order" type="uint" summary="color rendering fidelity order"/>
    </event>
  
    <!-- notify client of globally available standard profiles -->
    <event name="standard_profile">
      <description summary="global standard color profile">
          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. 
      </description>
      <arg name="profile_id" type="object" summary="associated color profile"/>
      <arg name="standard_profile" type="enum" summary="profile identifier"/>
    </event>
  
    <enum name="standard_profile">
      <description summary="standard ICC profiles">
        Globally available ICC profiles.
        </description>
        <entry name="sRGB" value="0" summary="sRGB profile"/>
      ....
    </enum>


    <!-- upload a client private source profile -->
    <request name="upload_source_profile">
      <arg name="profile_id" type="new_id" interface="client_color_manager"/>
      <arg name="fd" type="fd" summary="fd for reading ICC profile"/>
    </request>

    <event name="source_profile_uploaded">
      <description>
        The profile has been uploaded and the fd is no longer needed
      </description>
      <arg name="profile_id" type="id" interface="client_color_manager"/>
    </event>
  
    <!-- delete a client private source profile -->
    <request name="delete_source_profile">
      <arg name="profile_id" type="object" interface="client_color_manager"/>
    </request>
  

    <!-- tag a wl_buffer with source profile -->
    <request name="tag_buffer">
      <description summary="tag a wl_buffer with color source color profile.">
        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.

        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.
      </description>
      <arg name="wl_buffer" type="object" summary="buffer being tagged"/>
      <arg name="profile_id" type="object" interface="color_profile" />
        <arg name="hdr_max" type="fixed" summary="hdr max brightness"/>
        <arg name="hdr_diffuse" type="fixed" summary="hdr diffuse white"/>
    </request>


    <request name="get_buffer_profile_id">
      <description summary="Retrive a buffers color profile id.">
      </description>
      <arg name="wl_buffer" type="object" summary="buffer being tagged"/>
    </request>

    <!-- response to get_buffer_profile_id -->
    <event name="profile_id">
      <description summary="response to get_buffer_profile_id requestt">
      </description>
      <arg name="profile_id" type="object" summary="object being returned"/>
        <arg name="hdr_max" type="fixed" summary="hdr max brightness"/>
        <arg name="hdr_diffuse" type="fixed" summary="hdr diffuse white"/>
    </event>


    <!-- set the color intent for a wl_surface -->
    <request name="tag_surface">
      <description summary="set the color intent for a surface">
          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.
      </description>
      <arg name="wl_surface" type="object" summary="surface being tagged"/>
      <arg name="source_intent" type="enum" summary="source profile intent"/>
      <arg name="destination_intent" type="enum" summary="destination profile intent"/>
      <arg name="BPC" type="enum" summary="Black Point Compensation state"/>
        < HDR intent ~~~
    </request>
  
    <enum name="ICC_intent">
      <description summary="standard ICC rendering intent">
        </description>
        <entry name="icPerceptual"           value="0"/>
        <entry name="icRelativeColorimetric" value="1"/>
        <entry name="icSaturation"           value="2"/>
        <entry name="icAbsoluteColorimetric" value="3"/>
    </enum>

    <enum name="bpc">
      <description summary="black point compensation state">
        </description>
        <entry name="BPC_Dissabled" value="0"/>
        <entry name="BPC_Enabled"   value="1"/>
    </enum>


  </interface>
  
  <interface name="color_profile" version="1">
    <description summary="color profile">
      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.
    </description>

    <request name="download_color_profile">
      <description summary="get a color_profile">
        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.)
      </description>
      <arg name="profile_id" type="object" interface="color_profile"
           summary="color pofile"/>
    </request>

    <!-- response to get_color_profile -->
    <event name="profile">
      <description summary="response to get_color_profile requestt">
      </description>
      <arg name="profile_id" type="object" summary="object being returned"/>
      <arg name="fd" type="fd" summary="fd for reading ICC profile"/>
    </event>

    <request name="color_profile_downloaded">
      <description>
        The profile has been downloaded and the fd is no longer needed
      </description>
      <arg name="profile_id" type="object"/>
    </event>

  </interface>

</protocol">

~~~~
    <enum name="error">
      <description summary="global error values">
        These errors are global and can be emitted in response to any
        server request.
      </description>
      <entry name="incompatible_color_profile" value="2"
             summary="attempt to use a profile for a conversion direction it doesn't support"/>
      <entry name="invalid_color_profile_tag" value="2"
             summary="attempt to tag a buffer with an invalid wl_output profile"/>
~~~~
      <entry name="invalid_object" value="0"
             summary="server couldn't find object"/>
      <entry name="invalid_method" value="1"
             summary="method doesn't exist on the specified interface"/>
      <entry name="no_memory" value="2"
             summary="server is out of memory"/>
    </enum>

  </interface>

==============================================================================
==============================================================================

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="server_color_management_v1">

  <copyright>
    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.
  </copyright>

  <description summary="server color management protocol"">
    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.
  </description>


  <interface name="server_color_manager" version="1">
  
    <!-- upload and set the color profile for a wl_output -->
    <request name="upload_output_profile">
      <description summary="set wl_output color profile">
         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.
      </description>
      <arg name="output_id" type="object" summary="output"/>
      <arg name="fd" type="fd" summary="fd for reading ICC profile"/>
        <arg name="hdr_max" type="fixed" summary="hdr max brightness"/>
        <arg name="hdr_diffuse" type="fixed" summary="hdr diffuse white"/>
    </request>

    <event name="output_profile_uploaded">
      <description>
        The profile has been uploaded and the fd is no longer needed
      </description>
      <arg name="output_id" type="object" summary="output"/>
    </event>
  
    <request name="clear_output_profile">
      <description summary="turn color management off for the wl_output">
        This is a persistent configuration.
      </description>
      <arg name="output_id" type="object" summary="output"/>
    </request>

    <!-- set an outputs color fidelity order -->
    <request name="output_profile">
      <description summary="set wl_output color profile">
        This 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.
      </description>
      <arg name="output_id" type="object" summary="output"/>
        <arg name="fidelity_order" type="uint" summary="color rendering fidelity order"/>
    </request>
  
~~~ get 'vcgt' bit depths for a given wl_output

    <!-- temporarily override a wl_output 'vcgt' tag -->
    <request name="upload_teporary_vcgt">
      <description summary="temporarily override a wl_output 'vcgt' tag">
        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.
      </description>
      <arg name="output_id" type="object" summary="output"/>
      <arg name="fd" type="fd" summary="fd for reading ICC profile"/>
    </request>

    <request name="clear_temporary_vcgt">
      <description summary="restore the 'vcgt' state">
      </description>
      <arg name="output_id" type="object" summary="output"/>
    </request>

    <event name="temporary_vcgt_updated">
      <description>
        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.
      </description>
      <arg name="output_id" type="object" summary="output"/>
    </event>
  

    <request name="test_patch_surface">
~~~ 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 ?
      <description summary="Tag a wl_surface as being for color test patches">
        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
      </description>
      <arg name="wl_surface" type="object" summary="output"/>
~~~~    setting x,y should be request on role object ?
        or do we just create a new surface if we want to change size & position ?
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
    </request>
~~~~~~~~~~~~~
    <description summary="create color test patch surfaces">
      This interface is exposed as a global singleton.
      This interface is implemented by servers that provide server_color_management.
    </description>

    <enum name="error">
      <entry name="role" value="0" summary="given wl_surface has another role"/>
    </enum>

    <request name="surface_create">
      <description summary="create color test patch surface">
        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.
      </description>
      <arg name="surface" type="object" interface="wl_surface"/>
      <arg name="id" type="new_id" interface="color_test_patch_surface"/>
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
    </request>

~~~~~~~~~~~~~
    <!-- set a default source profile for all outputs -->
    <request name="set_default_profile">
      <description summary="set a default source color profile for all outputs.">
        The profile may be an output profile or a standard profile or null.
        If the profile that of the output or null, then all buffers
        will be interpretted as being in the wl_outputs color space
        and no color transform will be performed. 

        This is a persistent configuration.

        If an 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 PCS to buffer device 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.
      </description>
      <arg name="profile_id" type="object" interface="color_profile" />
        <arg name="hdr_max" type="fixed" summary="hdr max brightness"/>
        <arg name="hdr_diffuse" type="fixed" summary="hdr diffuse white"/>
    </request>

    <!-- In theory could allow per-output defaults, custom source default, custom
     per output intent. Is this useful enough to be worth the effort though ? -->

  </interface>

</protocol">

==============================================================================
==============================================================================

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="output_color_modification_v1">

  <copyright>
    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.
  </copyright>

  <description summary="output abstract color modification protocol">
    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
    whos purpose is to provide such display wide color modifications.
  </description>

  <interface name="output_color_modifier" version="1">
  
    <!-- upload and set the abstract color profile for a wl_output -->
    <event name="upload_abstract_profile">
      <description summary="set wl_output abstract color profile">
         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 scaleing to the destination PCS values
        to ensure that the source PCS white remains in gamut.
      </description>
      <arg name="output_id" type="object" summary="output"/>
      <arg name="fd" type="fd" summary="fd for reading ICC profile"/>
    </event>

    <event name="output_profile_uploaded">
      <description>
        The abstract profile has been uploaded and the fd is no longer needed
      </description>
      <arg name="output_id" type="object" summary="output"/>
    </event>
  
    <event name="clear_abstract_profile">
      <description summary="remove abstract profile for the wl_output">
      </description>
      <arg name="output_id" type="object" summary="output"/>
    </event>

  </interface>

</protocol">