diff --git a/src/client/protocols/output-management.xml b/src/client/protocols/output-management.xml index 9ebe342..c84cc54 100644 --- a/src/client/protocols/output-management.xml +++ b/src/client/protocols/output-management.xml @@ -1,163 +1,168 @@ Copyright © 2008-2011 Kristian Høgsberg Copyright © 2010-2011 Intel Corporation Copyright © 2012-2013 Collabora, Ltd. + Copyright © 2015 Sebastian Kügler Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of the copyright holders not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. The copyright holders make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ]]> - - This interface allows to connected output devices for screen configuration purposes. + + This interface enables clients to set properties of output devices for screen + configuration purposes via the server. To this end output devices are referenced + by global org_kde_kwin_outputdevice objects. - OutputManagement (wl_global) + outputmanagement (wl_global) -------------------------- request: - * createConfiguration -> OutputConfiguration (wl_resource) + * create_configuration -> outputconfiguration (wl_resource) - OutputConfiguration (wl_resource) + outputconfiguration (wl_resource) -------------------------- requests: - * enable(output, bool) - * mode(output, mode_id) - * transformation(output, flag) - * position(output, x, y) + * enable(outputdevice, bool) + * mode(outputdevice, mode_id) + * transformation(outputdevice, flag) + * position(outputdevice, x, y) * apply events: * applied * failed - The idea is that we register one OutputManagement as a global. When KScreen - wants to configure it calls createConfiguration which provides a resource - referencing an OutputConfiguration for one-time configuration. That way we can - easily group all requests and know on the server which one belong together. On - the OutputConfiguration it calls for each Output whether it's enabled, which - mode to use (by referencing the mode from the list of announced modes) and the - global position. Once all outputs are configured that way, it calls apply. At - that point and not earlier the server emits a signal to KWin with the complete - wanted configuration which KWin can then try to apply. If that succeeds it - emits the applied signal, otherwise the failed. So even KScreen can know about - it. + The server registers one outputmanagement object as a global object. In order + to configure outputs a client requests create_configuration, which provides a + resource referencing an outputconfiguration for one-time configuration. That + way the server knows which requests belong together and can group them by that. - That interface is nicely atomic (as KWin only gets the apply for everything - setup), it solves the 1:n mapping problem: each OutputConfiguration is only a - 1:1 mapping, and we do not need to copy all the requests again by just - referencing a mode id. + On the outputconfiguration object the client calls for each output whether the + output should be enabled, which mode should be set (by referencing the mode from + the list of announced modes) and the output's global position. Once all outputs + are configured that way, the client calls apply. + At that point and not earlier the server should try to apply the configuration. + If this succeeds the server emits the applied signal, otherwise the failed + signal, such that the configuring client is noticed about the success of its + configuration request. + Through this design the interface enables atomic output configuration changes if + internally supported by the server. - - Request an output configuration, which can be changed and then applied. + + Request an outputconfiguration object through which the client can configure + output devices. - - + outputconfiguration is a client-specific resource that can be used to ask - the compositor to apply changes to the outputdevices, the monitors connected - to the system. - The client receives a list of outputdevices from the registry. When it wants + the server to apply changes to available output devices. + + The client receives a list of output devices from the registry. When it wants to apply new settings, it creates a configuration object from the outputmanagement global, writes changes through this object's enable, scale, - transform and mode calls. It then asks the compositor to apply these settings - in an atomic fashion, for example through Linux's DRM interface. - The compositor signals back whether the new settings have applied successfully - or failed to apply. outputdevices are updated after the hardware changes have - been applied and before the server side fires applied. + transform and mode calls. It then asks the server to apply these settings in + an atomic fashion, for example through Linux' DRM interface. + + The server signals back whether the new settings have applied successfully + or failed to apply. outputdevice objects are updated after the changes have been + applied to the hardware and before the server side sends the applied event. Mark the output as enabled or disabled. - - + + - + Sets the mode for a given output by its mode size (width and height) and refresh rate. - + Sets the transformation for a given output. - - Sets the position for this output device in the global space. position - describes the top-left border of the output in the global space. The - left-most output's top-left border is 0, 0. - There may be no gaps between outputs, the outputs have to be positioned - stacked horizontally, vertically, or both. + + Sets the position for this output device. (x,y) describe the top-left corner + of the output in global space, whereby the origin (0,0) of the global space + has to be aligned with the top-left corner of the most left and in case this + does not define a single one the top output. + + There may be no gaps or overlaps between outputs, i.e. the outputs are + stacked horizontally, vertically, or both on each other. - - Sets the scaling factor for this outputdevice. + + Sets the scaling factor for this output device. - - Asks the compositor to apply changes to the outputdevices on the server side. + + Asks the server to apply property changes requested through this outputconfiguration + object to all outputs on the server side. - - Fired after the compositor has applied the changes successfully. + Sent after the server has successfully applied the changes. + . - Fired if the compositor rejects or failed to apply the changes. + Sent if the server rejects the changes or failed to apply them. diff --git a/src/client/protocols/outputdevice.xml b/src/client/protocols/outputdevice.xml index 747fc26..5598bb7 100644 --- a/src/client/protocols/outputdevice.xml +++ b/src/client/protocols/outputdevice.xml @@ -1,225 +1,236 @@ Copyright © 2008-2011 Kristian Høgsberg Copyright © 2010-2011 Intel Corporation Copyright © 2012-2013 Collabora, Ltd. + Copyright © 2015 Sebastian Kügler Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of the copyright holders not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. The copyright holders make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ]]> - - An outputdevice describes a physical monitor connected to the system. - outputdevice is similar to wl_output, but focuses on screen - management. The screen configuration client uses outputdevices to - enlist connected devices, even those that may currently not be used - by the compositor as wl_output. It sends configuration changes to the - compositor through the outputconfiguration interface, which applies the - settings to the hardware and signals changes the outputdevices + + An outputdevice describes a display device available to the compositor. + outputdevice is similar to wl_output, but focuses on output + configuration management. + + A client can query all global outputdevice objects to enlist all + available display devices, even those that may currently not be + represented by the compositor as a wl_output. + + The client sends configuration changes to the server through the + outputconfiguration interface, and the server applies the configuration + changes to the hardware and signals changes to the outputdevices accordingly. - This object is published as global during start up, or when a monitor - is hotplugged. + + This object is published as global during start up for every available + display devcies, or when one later becomes available, for example by + being hotplugged via a physical connector. - This enumeration describes how the physical - pixels on an output are laid out. + This enumeration describes how the physical pixels on an output are + laid out. - This describes the transform that a compositor will apply to a + This describes the transform, that a compositor will apply to a surface to compensate for the rotation or mirroring of an output device. The flipped values correspond to an initial flip around a vertical axis followed by rotation. - The purpose is mainly to allow clients render accordingly and + The purpose is mainly to allow clients to render accordingly and tell the compositor, so that for fullscreen surfaces, the - compositor will still be able to scan out directly from client - surfaces. + compositor is still able to scan out directly client surfaces. - + The geometry event describes geometric properties of the output. The event is sent when binding to the output object and whenever any of the properties change. - These flags describe properties of an output mode. - They are used in the flags bitfield of the mode event. + These flags describe properties of an output mode. They are + used in the flags bitfield of the mode event. - + The mode event describes an available mode for the output. - The event is sent when binding to the output object and there - will always be one mode, the current mode. The event is sent - again if an output changes mode, for the mode that is now - current. In other words, the current mode is always the last - mode that was received with the current flag set. + When the client binds to the outputdevice object, the server sends this + event once for every available mode the outputdevice can be operated by. + + There will always be at least one event sent out on initial binding, + which represents the current mode. + + Later on if an output changes its mode the event is sent again, whereby + this event represents the mode that has now become current. In other + words, the current mode is always represented by the latest event sent + with the current flag set. - The size of a mode is given in physical hardware units of - the output device. This is not necessarily the same as - the output size in the global compositor space. For instance, - the output may be scaled, as described in org_kde_kwin_outputdevice.scale, - or transformed , as described in org_kde_kwin_outputdevice.transform. + The size of a mode is given in physical hardware units of the output device. + This is not necessarily the same as the output size in the global compositor + space. For instance, the output may be scaled, as described in + org_kde_kwin_outputdevice.scale, or transformed, as described in + org_kde_kwin_outputdevice.transform. - The id can be used to refer to a mode when calling - set_mode on a org_kde_kwin_outputonfiguration. + The id can be used to refer to a mode when calling set_mode on an + org_kde_kwin_outputconfiguration object. - This event is sent after all other properties has been - sent after binding to the output object and after any - other property changes done after that. This allows - changes to the output properties to be seen as - atomic, even if they happen via multiple events. + This event is sent after all other properties have been + sent on binding to the output object as well as after any + other output property change have been applied later on. + This allows to see changes to the output properties as atomic, + even if multiple events successively announce them. This event contains scaling geometry information that is not in the geometry event. It may be sent after binding the output object or if the output scale changes later. If it is not sent, the client should assume a scale of 1. A scale larger than 1 means that the compositor will automatically scale surface buffers by this amount - when rendering. This is used for very high resolution + when rendering. This is used for high resolution displays where applications rendering at the native resolution would be too small to be legible. It is intended that scaling aware clients track the current output of a surface, and if it is on a scaled output it should use wl_surface.set_buffer_scale with the scale of the output. That way the compositor can avoid scaling the surface, and the client can supply a higher detail image. The edid event encapsulates the EDID data for the outputdevice. The event is sent when binding to the output object. The EDID - data may be empty, in which case this event is fired, anyway. + data may be empty, in which case this event is sent anyway. If the EDID information is empty, you can fall back to the name et al. properties of the outputdevice. - + Describes whether a device is enabled, i.e. device is used to display content by the compositor. This wraps a boolean around an int to avoid a boolean trap. - + The enabled event notifies whether this output is currently - enabled and used for displaying content the wayland server. - The event is sent when binding to the output object, and when - an output is enabled or disabled. + enabled and used for displaying content by the server. + The event is sent when binding to the output object and + whenever later on an output changes its state by becoming + enabled or disabled. - + - The uuid can be used to identify the output. It's controlled by the server entirely. - The compositor should make sure the uuid is persistant across restarts. - An empty uuid is considered invalid. + The uuid can be used to identify the output. It's controlled by + the server entirely. The server should make sure the uuid is + persistant across restarts. An empty uuid is considered invalid. - +