hyprland-protocols/protocols/hyprland-surface-v1.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="hyprland_surface_v1">
  <copyright>
    Copyright © 2025 outfoxxed
    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:

    1. Redistributions of source code must retain the above copyright notice, this
       list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright notice,
       this list of conditions and the following disclaimer in the documentation
       and/or other materials provided with the distribution.

    3. Neither the name of the copyright holder nor the names of its
       contributors may be used to endorse or promote products derived from
       this software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  </copyright>

  <description summary="hyprland-specific wl_surface extensions">
    This protocol exposes hyprland-specific wl_surface properties.
  </description>

  <interface name="hyprland_surface_manager_v1" version="1">
    <description summary="manager for hyprland surface objects">
      This interface allows a client to create hyprland surface objects.
    </description>

    <request name="get_hyprland_surface">
      <description summary="create a hyprland surface object">
        Create a hyprland surface object for the given wayland surface.

        If the wl_surface already has an associated hyprland_surface_v1 object,
        even from a different manager, creation is a protocol error.
      </description>

      <arg name="id" type="new_id" interface="hyprland_surface_v1"/>
      <arg name="surface" type="object" interface="wl_surface"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy the hyprland surface manager">
        Destroy the surface manager.
        This does not destroy existing surface objects.
      </description>
    </request>

    <enum name="error">
      <entry name="already_constructed" value="0" summary="wl_surface already has a hyprland surface object"/>
    </enum>
  </interface>

  <interface name="hyprland_surface_v1" version="1">
    <description summary="hyprland-specific wl_surface properties">
      This interface allows access to hyprland-specific properties of a wl_surface.

      Once the wl_surface has been destroyed, the hyprland surface object must be
      destroyed as well. All other operations are a protocol error.
    </description>

    <request name="set_opacity">
      <description summary="set the overall opacity of the surface">
        Sets a multiplier for the overall opacity of the surface.
        This multiplier applies to visual effects such as blur behind the surface
        in addition to the surface's content.

        The default value is 1.0.
        Setting a value outside of the range 0.0 - 1.0 (inclusive) is a protocol error.
        Does not take effect until wl_surface.commit is called.
      </description>

      <arg name="opacity" type="fixed"/>
    </request>

    <request name="destroy" type="destructor">
      <description summary="destroy the hyprland surface interface">
        Destroy the hyprland surface object, resetting properties provided
        by this interface to their default values on the next wl_surface.commit.
      </description>
    </request>

    <enum name="error">
      <entry name="no_surface" value="0" summary="wl_surface was destroyed"/>
      <entry name="out_of_range" value="1" summary="given opacity was not in the range 0.0 - 1.0 (inclusive)"/>
    </enum>
  </interface>
</protocol>