wl-mitm/proto/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="2">
    <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="2">
    <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>

    <request name="set_visible_region" since="2">
      <description summary="set the visible region of the surface">
        This request sets the region of the surface that contains visible content.
        Visible content refers to content that has an alpha value greater than zero.

        The visible region is an optimization hint for the compositor that lets it
        avoid drawing parts of the surface that are not visible. Setting a visible region
        that does not contain all content in the surface may result in missing content
        not being drawn.

        The visible region is specified in buffer-local coordinates.

        The compositor ignores the parts of the visible region that fall outside of the surface.
        When all parts of the region fall outside of the buffer geometry, the compositor may
        avoid rendering the surface entirely.

        The initial value for the visible region is empty. Setting the
        visible region has copy semantics, and the wl_region object can be destroyed immediately.
        A NULL wl_region causes the visible region to be set to empty.

        Does not take effect until wl_surface.commit is called.
      </description>

      <arg name="region" type="object" interface="wl_region" allow-null="true"/>
    </request>
  </interface>
</protocol>