From 03755785a5b741b500fd7c20d40b040410de2f0c Mon Sep 17 00:00:00 2001 From: Marius Vlad Date: Fri, 12 Jun 2020 21:00:41 +0300 Subject: README: move README.md to doc/ Bug-AGL: SPEC-3386 Signed-off-by: Marius Vlad Change-Id: If1acb6f0c4cfb9cdfa16e9fb8b57b29a1a596459 --- README.md | 211 ---------------------------------------------------------- doc/README.md | 211 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 211 insertions(+), 211 deletions(-) delete mode 100644 README.md create mode 100644 doc/README.md diff --git a/README.md b/README.md deleted file mode 100644 index 0a9d110..0000000 --- a/README.md +++ /dev/null @@ -1,211 +0,0 @@ -# agl-compositor - -## Design and overall architecture - -The compositor is built on top of libweston and on libweston-desktop. The -latter, among other things, is required as it provides the server side -implementation of the XDG shell protocol which underlying toolkits -(like qtwayland/chromium) make use to deliver desktop like functionality. -The former is used to provide back-ends and rendering support, besides -implementing the wayland protocol. - -xdg-shell is currently de facto protocol for handling all window management -related functionality. In order to avoid polluting the wayland protocol -namespace, the XDG extension, together with some other useful protocols, like -the linux-dmabuf one, are all developed under the wayland-protocols umbrella. - -The whole purpose of wayland-protocols is to enhance the Wayland protocol with -new functionality and bring new extensions entirely. Compositors are free to -implement, modify, enhance, and add new extensions to wayland-protocols but -they need to do so in consensus. - -Besides the core wayland protocol and extended functionality from -wayland-protocols, a compositor can provide additional protocol extension -specifications (obviously specific to that compositor). agl-compositor uses -private extensions to deliver specific functionality or improve the current -functionality to align with AGL demands. See [protocol extension](#protocol-extensions) -about them. - -Traditionally, clients were entirely separated from the window manager, the -desktop environment and the server. In wayland all these are conceptually under -the same entity though they are implemented as different UNIX processes, or a -different namespace with front and back-end APIs, exposed by different -libraries. As such, the compositor and the shell driving the UI should be seen -as one and the same, and in practice, this happens on traditional desktop -environments. - -agl-compositor has logic in place to spawn/run the shell, but in case of AGL, -the shell can be represented under different forms, as well as the fact that -the process management has another layer baked in to handle MAC (Mandatory -Access Control) labels and use a custom application framework -management. These are all tightly integrated and therefore, the agl-compositor -will not automatically start the shell client, although there's code to handle -that. - -## Customizing and tailoring the compositor - -The compositor only adds basic functionality, and depending on use-cases, one -might want to further enhance or tailor the compositor to fit their need. The -compositor only contains the bare minimum, necessary bits to bring up the -screen and make use of private extensions to integrate better with the existing -AGL infrastructure. It is encouraged and desirable to modify the compositor if -more customization is required. - -## Protocol extensions - -Compositors can define and implement custom extensions to further control -application behaviour. For AGL, respectively, for agl-compositor, we have two -private extensions defined. One targeted at defining surface roles commonly -found desktop environments (like panels, and backgrounds), which acts as the -shell client, and one targeted at regular application(s) that might require -additional functionality. - -This document describes the overall functionality and some implementation -details and potential corner-cases. Refer to the protocol XML specification for -further and up-to-date documentation. - -### Surface roles - -Internally, agl-compositor assigns to regular XDG applications, a default, -desktop role. Further roles like a background or a panel, are available to -further customize layer and orientation of surfaces. - -These have **no** particular meaning, except that it hints the compositor where -they should be stacked or where to position them. The background one occupies -the most lower layer, the desktop ones on top and the panel surfaces the upper -most layer. - -Additional roles have been added, in a different extension, to add further -functionality with the control/security functions being transferred over to a -policy framework in case that is necessary. See [policy api][#policy] for -further details. - -### agl-shell - -Clients can make use of this protocol to define different kind of roles for -different kind of surfaces. This defines panels and a background surface. It -includes to ability to activate other applications, assuming that those are -already running. Activation happens by using using the app_id, respectively -using set_app_id request as defined by the XDG shell protocol. Established -client-side implementation of the XDG shell protocol will have a function used -to set it up, or it should provide or expose an API to do so. - -Clients will be **required** to set their application ids accordingly in order -for the client shell to activate them. - -### agl-shell-desktop - -This extension is targeted at keeping some of the functionally already -established in AGL a) to allow applications display/activate other -surfaces/application window, and b) to set further roles, specially dialog -pop-ups and split-type of surfaces. - -Clients can make use of this protocol to set further roles, like independently -positioned pop-up dialog windows, split type of surfaces or fullscreen ones. -Additional roles can be added by extending the protocol. These roles serve as -hints for the compositor and should be used before the actual surface creation -takes place such that the compositor can take the necessary steps to ensure -those requirements. - -#### Additional surface roles - -Like mentioned earlier, the compositor is already making use of some (internal) -roles, and with this extension we add some further roles. These are: split -(there's vertical and a horizontal one), fullscreen, and pop-up one. Internally -these are encoded with different values such that there's a translation needed, -between the protocol values and the internal values. - -Besides the roles, additional data can to be passed, but only relevant -depending on the role. - -#### Receiving application state events from (other) applications - -agl-shell-desktop exposes two events which client can install handlers for, one -that signals when regular XDG application have been created, and one that -signals state changes (active/hidden) as well as destroyed/no longer present -surfaces. These events can be useful to add additional functionality if -needed. - -### Activating (other) applications - -Both agl-shell and agl-shell-desktop have requests to activate other -application based on their XDG shell app_id. In case the application is -present/running it it will attempt to make the surface backing that application -the current activate one, with each output having independently active -surfaces. - -### Explicit output - -The activation and setting surface roles requires passing an output -(wl_output). The output is the wayland interface representation of an output -and is **mandatory**. Clients can retrieve it (the output) if they wish to -place the surface on other outputs by using the toolkits exposing wayland -objects. A human-like representation is provided by binding directly, by using -other extension implemented by the client (i.e., xdg_output is the one -recommended) or by using abstraction implementation written on top. - -### Protocol design, future work and potential improvements - -Both protocols assume immediate, synchronous behaviour and to some extent lack -some error handling functionality. - -Role assignment to surfaces could probably be improved with an additional -interface with can add further data, if that roles assumes that to be true. - -There seems to be some overlapping functionality with respect to activating -applications, so a potential improvement would be that the agl-shell protocol -only contains the ability to set shell related surface roles, and -agl-shell-desktop to be used when needing to activate applications. -For the client shell this means that it will need to bind to both of the -extensions, one that set-ups the background and panel roles, with the other -needed to activate applications. - -## Policy - -The compositor contains an API useful for defining policy rules. It contains -the bare minimum and installs, by default, an allow-all kind of engine. - -Users wanting to create their own policy engine should create a specialized -version and use `struct ivi_policy_api` where they can install their own -callbacks. - -The default policy found in src/policy-default.c should more than sufficient to -get started. Users can either re-puporse the default policy or create a new one -entirely different, based on their needs. - -### Hooks - -These are hooks for allowing the creation, committing and activation of surfaces -(`ivi_policy_api::surface_create()`, `ivi_policy_api::surface_commited()`, - `ivi_policy_api::surface_activate()`). - -Another hook, `ivi_policy_api::policy_rule_allow_to_add()` can be used to -control if policy rules (the next type) can be added or not. Finally, we have -`ivi_policy_api::policy_rule_try_event()` which is executed for each policy -rules currently added, by using the policy API `ivi_policy_add()`. - -Users can customize the hooks by using some sort of database to retrieve -the application name to compare against, or incorporate some kind of policy -rule engine. - -### Policy rules - -Policy (injection) rules can be added using the policy API framework. The -protocol allows to define policy rules that should be executed by using the -`ivi_policy_api::policy_rule_try_event()` callback. These are particularly useful -when handling state changes. The framework API allows adding new states and -events and the default implementation has code for handling events like showing -or hiding the application specified in the policy rule. - -#### Default events and states - -By default the when creating the policy framework it will add the 'show', and -'hide' events and the 'start', 'stop' and 'reverse' states. An special type, -assigned by default is 'invalid'. - -#### State changes - -A state change has to be propaged from to the compositor, by using -`ivi_policy_state_change()`, to signal the compositor the (state) change itself, -in order to apply the policy rules, and implicitly to call the event -handler `ivi_policy_api::policy_rule_try_event()`. diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..0a9d110 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,211 @@ +# agl-compositor + +## Design and overall architecture + +The compositor is built on top of libweston and on libweston-desktop. The +latter, among other things, is required as it provides the server side +implementation of the XDG shell protocol which underlying toolkits +(like qtwayland/chromium) make use to deliver desktop like functionality. +The former is used to provide back-ends and rendering support, besides +implementing the wayland protocol. + +xdg-shell is currently de facto protocol for handling all window management +related functionality. In order to avoid polluting the wayland protocol +namespace, the XDG extension, together with some other useful protocols, like +the linux-dmabuf one, are all developed under the wayland-protocols umbrella. + +The whole purpose of wayland-protocols is to enhance the Wayland protocol with +new functionality and bring new extensions entirely. Compositors are free to +implement, modify, enhance, and add new extensions to wayland-protocols but +they need to do so in consensus. + +Besides the core wayland protocol and extended functionality from +wayland-protocols, a compositor can provide additional protocol extension +specifications (obviously specific to that compositor). agl-compositor uses +private extensions to deliver specific functionality or improve the current +functionality to align with AGL demands. See [protocol extension](#protocol-extensions) +about them. + +Traditionally, clients were entirely separated from the window manager, the +desktop environment and the server. In wayland all these are conceptually under +the same entity though they are implemented as different UNIX processes, or a +different namespace with front and back-end APIs, exposed by different +libraries. As such, the compositor and the shell driving the UI should be seen +as one and the same, and in practice, this happens on traditional desktop +environments. + +agl-compositor has logic in place to spawn/run the shell, but in case of AGL, +the shell can be represented under different forms, as well as the fact that +the process management has another layer baked in to handle MAC (Mandatory +Access Control) labels and use a custom application framework +management. These are all tightly integrated and therefore, the agl-compositor +will not automatically start the shell client, although there's code to handle +that. + +## Customizing and tailoring the compositor + +The compositor only adds basic functionality, and depending on use-cases, one +might want to further enhance or tailor the compositor to fit their need. The +compositor only contains the bare minimum, necessary bits to bring up the +screen and make use of private extensions to integrate better with the existing +AGL infrastructure. It is encouraged and desirable to modify the compositor if +more customization is required. + +## Protocol extensions + +Compositors can define and implement custom extensions to further control +application behaviour. For AGL, respectively, for agl-compositor, we have two +private extensions defined. One targeted at defining surface roles commonly +found desktop environments (like panels, and backgrounds), which acts as the +shell client, and one targeted at regular application(s) that might require +additional functionality. + +This document describes the overall functionality and some implementation +details and potential corner-cases. Refer to the protocol XML specification for +further and up-to-date documentation. + +### Surface roles + +Internally, agl-compositor assigns to regular XDG applications, a default, +desktop role. Further roles like a background or a panel, are available to +further customize layer and orientation of surfaces. + +These have **no** particular meaning, except that it hints the compositor where +they should be stacked or where to position them. The background one occupies +the most lower layer, the desktop ones on top and the panel surfaces the upper +most layer. + +Additional roles have been added, in a different extension, to add further +functionality with the control/security functions being transferred over to a +policy framework in case that is necessary. See [policy api][#policy] for +further details. + +### agl-shell + +Clients can make use of this protocol to define different kind of roles for +different kind of surfaces. This defines panels and a background surface. It +includes to ability to activate other applications, assuming that those are +already running. Activation happens by using using the app_id, respectively +using set_app_id request as defined by the XDG shell protocol. Established +client-side implementation of the XDG shell protocol will have a function used +to set it up, or it should provide or expose an API to do so. + +Clients will be **required** to set their application ids accordingly in order +for the client shell to activate them. + +### agl-shell-desktop + +This extension is targeted at keeping some of the functionally already +established in AGL a) to allow applications display/activate other +surfaces/application window, and b) to set further roles, specially dialog +pop-ups and split-type of surfaces. + +Clients can make use of this protocol to set further roles, like independently +positioned pop-up dialog windows, split type of surfaces or fullscreen ones. +Additional roles can be added by extending the protocol. These roles serve as +hints for the compositor and should be used before the actual surface creation +takes place such that the compositor can take the necessary steps to ensure +those requirements. + +#### Additional surface roles + +Like mentioned earlier, the compositor is already making use of some (internal) +roles, and with this extension we add some further roles. These are: split +(there's vertical and a horizontal one), fullscreen, and pop-up one. Internally +these are encoded with different values such that there's a translation needed, +between the protocol values and the internal values. + +Besides the roles, additional data can to be passed, but only relevant +depending on the role. + +#### Receiving application state events from (other) applications + +agl-shell-desktop exposes two events which client can install handlers for, one +that signals when regular XDG application have been created, and one that +signals state changes (active/hidden) as well as destroyed/no longer present +surfaces. These events can be useful to add additional functionality if +needed. + +### Activating (other) applications + +Both agl-shell and agl-shell-desktop have requests to activate other +application based on their XDG shell app_id. In case the application is +present/running it it will attempt to make the surface backing that application +the current activate one, with each output having independently active +surfaces. + +### Explicit output + +The activation and setting surface roles requires passing an output +(wl_output). The output is the wayland interface representation of an output +and is **mandatory**. Clients can retrieve it (the output) if they wish to +place the surface on other outputs by using the toolkits exposing wayland +objects. A human-like representation is provided by binding directly, by using +other extension implemented by the client (i.e., xdg_output is the one +recommended) or by using abstraction implementation written on top. + +### Protocol design, future work and potential improvements + +Both protocols assume immediate, synchronous behaviour and to some extent lack +some error handling functionality. + +Role assignment to surfaces could probably be improved with an additional +interface with can add further data, if that roles assumes that to be true. + +There seems to be some overlapping functionality with respect to activating +applications, so a potential improvement would be that the agl-shell protocol +only contains the ability to set shell related surface roles, and +agl-shell-desktop to be used when needing to activate applications. +For the client shell this means that it will need to bind to both of the +extensions, one that set-ups the background and panel roles, with the other +needed to activate applications. + +## Policy + +The compositor contains an API useful for defining policy rules. It contains +the bare minimum and installs, by default, an allow-all kind of engine. + +Users wanting to create their own policy engine should create a specialized +version and use `struct ivi_policy_api` where they can install their own +callbacks. + +The default policy found in src/policy-default.c should more than sufficient to +get started. Users can either re-puporse the default policy or create a new one +entirely different, based on their needs. + +### Hooks + +These are hooks for allowing the creation, committing and activation of surfaces +(`ivi_policy_api::surface_create()`, `ivi_policy_api::surface_commited()`, + `ivi_policy_api::surface_activate()`). + +Another hook, `ivi_policy_api::policy_rule_allow_to_add()` can be used to +control if policy rules (the next type) can be added or not. Finally, we have +`ivi_policy_api::policy_rule_try_event()` which is executed for each policy +rules currently added, by using the policy API `ivi_policy_add()`. + +Users can customize the hooks by using some sort of database to retrieve +the application name to compare against, or incorporate some kind of policy +rule engine. + +### Policy rules + +Policy (injection) rules can be added using the policy API framework. The +protocol allows to define policy rules that should be executed by using the +`ivi_policy_api::policy_rule_try_event()` callback. These are particularly useful +when handling state changes. The framework API allows adding new states and +events and the default implementation has code for handling events like showing +or hiding the application specified in the policy rule. + +#### Default events and states + +By default the when creating the policy framework it will add the 'show', and +'hide' events and the 'start', 'stop' and 'reverse' states. An special type, +assigned by default is 'invalid'. + +#### State changes + +A state change has to be propaged from to the compositor, by using +`ivi_policy_state_change()`, to signal the compositor the (state) change itself, +in order to apply the policy rules, and implicitly to call the event +handler `ivi_policy_api::policy_rule_try_event()`. -- cgit 1.2.3-korg