feresaria/protocols/ferese-effects-v1.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="ferese_effects_v1">
  <copyright>
    Copyright 2026 Ferese contributors

    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 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="ferese_effects_manager_v1" version="5">
    <description summary="assign semantic material roles to surfaces">
      This private global is visible only to clients granted the Ferese effects
      capability. Roles describe compositor-owned appearance policy and do not
      expose shader parameters or backdrop content to the client.
    </description>

    <request name="destroy" type="destructor">
      <description summary="destroy the manager binding"/>
    </request>

    <request name="get_surface_effects">
      <description summary="create semantic effects state for a surface">
        A wl_surface can have at most one live surface-effects object. Creating
        another object for the same surface is a protocol error.
      </description>
      <arg name="id" type="new_id" interface="ferese_surface_effects_v1"/>
      <arg name="surface" type="object" interface="wl_surface"/>
    </request>

    <enum name="error">
      <entry name="already_constructed" value="0"
             summary="the surface already has an effects object"/>
    </enum>
  </interface>

  <interface name="ferese_surface_effects_v1" version="5">
    <description summary="semantic material role for one surface">
      The role affects only compositor rendering. It does not change surface
      geometry, input, focus, stacking, or the surface's Wayland role.
    </description>

    <request name="destroy" type="destructor">
      <description summary="clear the role and destroy this object"/>
    </request>

    <request name="set_role">
      <description summary="set the semantic material role">
        The most recent valid role replaces the previous role atomically.
      </description>
      <arg name="role" type="uint" enum="role"/>
    </request>

    <request name="clear_role">
      <description summary="clear the semantic material role"/>
    </request>

    <enum name="role">
      <entry name="panel" value="0" summary="persistent panel surface"/>
      <entry name="panel_elevated" value="1" summary="raised panel surface"/>
      <entry name="popover" value="2" summary="transient popover"/>
      <entry name="menu" value="3" summary="menu surface"/>
      <entry name="notification" value="4" summary="notification surface"/>
      <entry name="hud" value="5" summary="heads-up display surface"/>
      <entry name="modal" value="6" summary="modal surface"/>
    </enum>

    <request name="set_regions" since="2">
      <description summary="restrict material to rounded surface-local rectangles">
        An array of native-endian IEEE 754 binary32 tuples (x, y, width, height,
        radius) in logical pixels. All values must be finite and have magnitude
        at most 32768; width and height must be positive and radius nonnegative.
        At most 32 rectangles are allowed. Invalid arrays are ignored.
        Coordinates are rounded only after output scaling.
        An empty array disables material painting without clearing the role.
        Surfaces which never send this request retain full-surface materials.
      </description>
      <arg name="regions" type="array"/>
    </request>
    <request name="set_opacity" since="3">
      <description summary="fade the complete surface presentation">
        Opacity from 0 to 1000, including surface content, material and shadow.
        Values above 1000 are clamped. Input and geometry remain unchanged.
      </description>
      <arg name="opacity" type="uint"/>
    </request>
    <request name="set_region_opacities" since="4">
      <description summary="fade individual region materials and shadows">
        An array of native-endian uint32 opacity values from 0 to 1000,
        indexed in set_regions order. Content is not affected. Missing entries
        use 1000. At most 32 entries are allowed; invalid arrays are ignored.
        These values multiply the surface opacity and persist until replaced.
      </description>
      <arg name="opacities" type="array"/>
    </request>
    <request name="set_presentation" since="5">
      <description summary="apply material presentation with the next surface commit">
        Queue the role, regions, surface opacity and region opacities together.
        They take effect on the next wl_surface.commit, with its content buffer.
        Array formats and limits match set_regions and set_region_opacities.
        Invalid arrays or roles leave the pending state unchanged. Surface opacity
        is clamped to 1000. The last valid request before a commit wins.
        Compositor-owned dismissal retains control of surface opacity.
      </description>
      <arg name="role" type="uint" enum="role"/>
      <arg name="regions" type="array"/>
      <arg name="opacity" type="uint"/>
      <arg name="region_opacities" type="array"/>
    </request>
  </interface>
</protocol>