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