summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorMarius Vlad <marius.vlad@collabora.com>2020-03-03 20:24:19 +0200
committerMarius Vlad <marius.vlad@collabora.com>2020-03-11 16:44:10 +0200
commit721d4d4f73e5d30ce9bc48fae5e1f1b8be34c23d (patch)
tree3d32ad03659618f1066d89575ca4522a58caf6f1 /README.md
parent0a932bc7d66b062e6bf9cdbe40a2178ed47dd6c8 (diff)
README.md: Start adding some light documentation on the policy part
Bug-AGL: SPEC-3217 Signed-off-by: Marius Vlad <marius.vlad@collabora.com> Change-Id: Ifdd6dda9dbe91e2783c4d3546e542aa2320d3707
Diffstat (limited to 'README.md')
-rw-r--r--README.md51
1 files changed, 51 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..77d2a04
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+# agl-compositor
+
+## 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().