diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.md | 211 |
1 files changed, 211 insertions, 0 deletions
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()`. |