doc/README.md

   1 # agl-compositor
   2
   3 ## Design and overall architecture
   4
   5 The compositor is built on top of libweston and on libweston-desktop. The
   6 latter, among other things, is required as it provides the server side
   7 implementation of the XDG shell protocol which underlying toolkits
   8 (like qtwayland/chromium) make use to deliver desktop like functionality.
   9 The former is used to provide back-ends and rendering support, besides
  10 implementing the wayland protocol.
  11
  12 ![high overview diagram of the compositor](arch_diagram.png "high overview diagram of the compositor")
  13
  14 xdg-shell is currently de facto protocol for handling all window management
  15 related functionality. In order to avoid polluting the wayland protocol
  16 namespace, the XDG extension, together with some other useful protocols, like
  17 the linux-dmabuf one, are all developed under the wayland-protocols umbrella.
  18
  19 The whole purpose of wayland-protocols is to enhance the Wayland protocol with
  20 new functionality and bring new extensions entirely. Compositors are free to
  21 implement, modify, enhance, and add new extensions to wayland-protocols but
  22 they need to do so in consensus.
  23
  24 Besides the core wayland protocol and extended functionality from
  25 wayland-protocols, a compositor can provide additional protocol extension
  26 specifications (obviously specific to that compositor). agl-compositor uses
  27 private extensions to deliver specific functionality or improve the current
  28 functionality to align with AGL demands. See [protocol extension](#protocol-extensions)
  29 about them.
  30
  31 Traditionally, clients were entirely separated from the window manager, the
  32 desktop environment and the server. In wayland all these are conceptually under
  33 the same entity though they are implemented as different UNIX processes, or a
  34 different namespace with front and back-end APIs, exposed by different
  35 libraries.  As such, the compositor and the shell driving the UI should be seen
  36 as one and the same, and in practice, this happens on traditional desktop
  37 environments.
  38
  39 agl-compositor has logic in place to spawn/run the shell, but in case of AGL,
  40 the shell can be represented under different forms, as well as the fact that
  41 the process management has another layer baked in to handle MAC (Mandatory
  42 Access Control) labels and use a custom application framework
  43 management. These are all tightly integrated and therefore, the agl-compositor
  44 will not automatically start the shell client, although there's code to handle
  45 that.
  46
  47 ## Customizing and tailoring the compositor
  48
  49 The compositor only adds basic functionality, and depending on use-cases, one
  50 might want to further enhance or tailor the compositor to fit their need.  The
  51 compositor only contains the bare minimum, necessary bits to bring up the
  52 screen and make use of private extensions to integrate better with the existing
  53 AGL infrastructure. It is encouraged and desirable to modify the compositor if
  54 more customization is required.
  55
  56 ## Protocol extensions
  57
  58 Compositors can define and implement custom extensions to further control
  59 application behaviour. For AGL, respectively, for agl-compositor, we have two
  60 private extensions defined. One targeted at defining surface roles commonly
  61 found desktop environments (like panels, and backgrounds), which acts as the
  62 shell client, and one targeted at regular application(s) that might require
  63 additional functionality.
  64
  65 This document describes the overall functionality and some implementation
  66 details and potential corner-cases. Refer to the protocol XML specification for
  67 further and up-to-date documentation.
  68
  69 ### Surface roles
  70
  71 Internally, agl-compositor assigns to regular XDG applications, a default,
  72 desktop role. Further roles like a background or a panel, are available to
  73 further customize layer and orientation of surfaces.
  74
  75 These have **no** particular meaning, except that it hints the compositor where
  76 they should be stacked or where to position them. The background one occupies
  77 the lowest layer, with the desktop role ones on top of it, and the panel role
  78 surfaces on the uppermost layer.
  79
  80 Additional roles have been added, in a different extension, to add further
  81 functionality with the control/security functions being transferred over to a
  82 policy framework in case that is necessary. See [policy api](#policy) for
  83 further details.
  84
  85 ### agl-shell
  86
  87 Clients can make use of this protocol to define different kind of roles for
  88 different kind of surfaces. This defines panels and a background surface.  It
  89 includes the ability to activate other applications, assuming that those are
  90 already running. Activation happens by using the app_id, respectively
  91 using set_app_id request as defined by the XDG shell protocol. Established
  92 client-side implementation of the XDG shell protocol will have a function used
  93 to set it up, or it should provide or expose an API to do so.
  94
  95 Clients will be **required** to set their application ids accordingly in order
  96 for the client shell to activate them.
  97
  98 ### agl-shell-desktop
  99
 100 This extension is targeted at keeping some of the functionally already
 101 established in AGL a) to allow applications display/activate other
 102 surfaces/application window, and b) to set further roles, such as dialog
 103 pop-ups and split-type of surfaces.
 104
 105 Clients can make use of this protocol to set further roles, like independently
 106 positioned pop-up dialog windows, split type of surfaces or fullscreen ones.
 107 Additional roles can be added by extending the protocol. These roles serve as
 108 hints for the compositor and should be used before the actual surface creation
 109 takes place such that the compositor can take the necessary steps to ensure
 110 those requirements.
 111
 112 #### Additional surface roles
 113
 114 Like mentioned earlier, the compositor is already making use of some (internal)
 115 roles, and with this extension we add some further roles. These are: split
 116 (there's vertical and a horizontal one), fullscreen, and pop-up one. Internally
 117 these are encoded with different values such that there's a translation needed,
 118 between the protocol values and the internal values.
 119
 120 Besides the roles, additional data can be passed, but only relevant
 121 depending on the role.
 122
 123 #### Receiving application state events from (other) applications
 124
 125 agl-shell-desktop exposes two events which client can install handlers for, one
 126 that signals when regular XDG application have been created, and one that
 127 signals state changes (active/hidden) as well as destroyed/no longer present
 128 surfaces. These events can be useful to add additional functionality if
 129 needed.
 130
 131 ### Activating (other) applications
 132
 133 Both agl-shell and agl-shell-desktop have requests to activate other
 134 application based on their XDG shell app_id. In case the application is
 135 present/running, it will attempt to make the surface backing that application
 136 the current active one, with each output having independent active
 137 surfaces.
 138
 139 ### Explicit output
 140
 141 Activation and setting of surface roles requires passing an output
 142 (wl_output).  The output is the wayland interface representation of an output
 143 and is **mandatory**.  Clients can retrieve it (the output) if they wish to
 144 place the surface on other outputs by using the toolkits exposing wayland
 145 objects.  A human-like representation is provided by binding directly, by using
 146 other extension implemented by the client (i.e., xdg_output is the one
 147 recommended) or by using abstraction implementation written on top.
 148
 149 ### Protocol design, future work and potential improvements
 150
 151 Both protocols assume immediate, synchronous behaviour and to some extent lack
 152 some error handling functionality.
 153
 154 Role assignment to surfaces could probably be improved with an additional
 155 interface that could add further data, if a role requires it.
 156
 157 There seems to be some overlapping functionality with respect to activating
 158 applications, so a potential improvement would be that the agl-shell protocol
 159 only contains the ability to set shell related surface roles, and
 160 agl-shell-desktop to be used when needing to activate applications.
 161 For the client shell this means that it will need to bind to both of the
 162 extensions, one that set-ups the background and panel roles, with the other
 163 needed to activate applications.
 164
 165 ## Policy
 166
 167 The compositor contains an API useful for defining policy rules.  It contains
 168 the bare minimum and installs, by default, an allow-all kind of engine. A
 169 deny-all policy engine exists and can be switched to by using
 170 `-Dpolicy-default=deny-all` build time option.
 171
 172 For instance, in order to configure the compositor with that policy one could
 173 issue:
 174
 175         $ meson -Dprefix=/path/to/where/to/install/compositor -Dpolicy-default=deny-all build_directory
 176
 177 Users wanting to create their own policy engine should create a specialized
 178 version and use `struct ivi_policy_api` where they can install their own
 179 callbacks.
 180
 181 The default policy found in src/policy-default.c should more than sufficient to
 182 get started. Users can either re-purpose the default policy or create a new one
 183 entirely different, based on their needs.
 184
 185 ### Hooks
 186
 187 These are hooks for allowing the creation, committing and activation of surfaces
 188 (`ivi_policy_api::surface_create()`, `ivi_policy_api::surface_commited()`,
 189  `ivi_policy_api::surface_activate()`).
 190
 191 Another hook, `ivi_policy_api::policy_rule_allow_to_add()` can be used to
 192 control if policy rules (the next type) can be added or not. Finally, we have
 193 `ivi_policy_api::policy_rule_try_event()` which is executed for each policy
 194 rules currently added, by using the policy API `ivi_policy_add()`.
 195
 196 Users can customize the hooks by using some sort of database to retrieve the
 197 application name to compare against, or incorporate some kind of policy rule
 198 engine.  Alternatively, one can use the deny-all policy engine which allows the
 199 top panel applications to be used/displayed as permitted applications.
 200
 201 ### Policy rules
 202
 203 Policy (injection) rules can be added using the policy API framework.  The
 204 protocol allows to define policy rules that should be executed by using the
 205 `ivi_policy_api::policy_rule_try_event()` callback. These are particularly useful
 206 when handling state changes. The framework API allows adding new states and
 207 events and the default implementation has code for handling events like showing
 208 or hiding the application specified in the policy rule.
 209
 210 #### Default events and states
 211
 212 By default, when creating the policy framework it will add the 'show', and
 213 'hide' events and the 'start', 'stop' and 'reverse' states. A special type,
 214 assigned by default is 'invalid'.
 215
 216 #### State changes
 217
 218 A state change has to be propaged from to the compositor, by using
 219 `ivi_policy_state_change()`, to signal the compositor the (state) change itself,
 220 in order to apply the policy rules, and implicitly to call the event
 221 handler `ivi_policy_api::policy_rule_try_event()`.