diff options
authorMichael Drake <>2017-06-11 15:55:35 +0100
committerMichael Drake <>2017-06-11 15:55:35 +0100
commit4e1b55215d62b41dc74151d2eecadb6e82bacfd1 (patch)
parent97f1da6870fcded40b58b5c9e6b53ff78094288d (diff)
Docs: Update architecture documentation.
1 files changed, 76 insertions, 3 deletions
diff --git a/docs/ b/docs/
index 7c5b091..26232c9 100644
--- a/docs/
+++ b/docs/
@@ -15,6 +15,7 @@ their types are used in the LibNSLayout interface:
* `LibDOM` is used to provide the DOM interface.
* `LibCSS` is used to provide the CSS handling.
* `LibWapcaplet` is used for interned strings.
+* `LibNSLog` for logging.
@@ -79,7 +80,7 @@ will:
3. Try to fit as many non-breakable sections on a line as possible, given
the available width.
-Note that some breaks may not be permissable, since they will fall inside
+Note that some breaks may not be permissible, since they will fall inside
inline elements which are styled to prevent wrap. Also, to measure each
non-breakable section, there may be multiple calls to the client to measure
sub-sections of the non-breakable section according to different parts of the
@@ -87,6 +88,78 @@ text having different styles. We can probably avoid this depending on which
CSS properties are different. (e.g. `color` and `text-decoration` won't affect
text measurement.)
-> **TODO**
+> **TODO**: How to do justified text?
-> 1. How to do justified text?
+> Probably we can measure the minimum space width needed on a line,
+> fit as much text as possible with that, and share any remaining space
+> out over each break-point that is a space.
+### Layout
+Layout will be lazy, and only actually done when prompted by the client.
+The client will be getting DOM modification events and informing LibNSLayout.
+LibNSLayout will be notified when elements are added and removed from the
+DOM, and when TEXT nodes are added/modified/removed.
+> **TODO**: How lazy to be?
+> We could either:
+> 1. Build/update layout tree as we get the updates (but not performing
+> layout until asked by the client).
+> 2. Queue DOM update events and elide updates that cancel themselves out.
+> For example if an element is added and immediately removed, there is
+> no point in doing anything. (Or is there? Consider starting fetches
+> as early as possible.) We would then only update the layout tree when
+> the queue gets too long or when the client requires a layout.
+If an element is added, we would perform CSS selection, and assuming its not
+got `display: none` we'd add the elements entry in the layout tree. When we
+add the new entry to the layout tree, we'd mark its parents as needing layout.
+We'd keep walking up the ancestor chain marking as needing layout until we hit
+a layout entry who's width and height are fixed, meaning it can't affect its
+parent layout.
+When the client requires a layout, we would then walk the tree, ensuring every
+layout node has a valid `x`, `y`, `width`, and `height`.
+### Rendering
+The client is responsible for rendering, and any compositing. When the
+client asks LibNSLayout to layout, LibNSLayout returns a render list.
+> **TODO**: Details?
+> 1. Consider render list optimisation (e.g. NetSurf's Knockout rendering).
+> 2. What will the render list look like.
+### Fetches
+There are several kinds of fetches to consider:
+* Fetch resources directly required by the document. (Client initiated.)
+ * CSS
+ * JavaScript
+ * Images
+ * Iframes
+ * etc...
+* Fetch resources required by element computed styles. (LibNSLayout
+ initiated.)
+ * Background images.
+ * Web fonts.
+For a client initiated fetch of CSS, the selection context is updated when
+we have fetched the style sheet, and LibNSLog is informed.
+For a LibNSLayout initiated fetch, LibNSLayout creates a `nsl_resource_t`
+and passes a pointer to to to the client, along with the URL to fetch.
+The `nsl_resource_t` is opaque to the client. When the resource is fetched,
+the client calls a callback passing, the `nsl_resource_t`, and a pointer to
+the client handle for the resource (`hlcache_handle`, in NetSurf). Then
+`LibNSLayout` can set the pointer to the client resource handle inside the
+`nsl_resource_t`, and the pointer will be used to ask the client about e.g.
+intrinsic dimensions. The pointer to the client handle will also appear in
+the render list that is given to the client for display.
+> **TODO**: How to do fetches started by client for e.g. images, that
+> LibNSLayout needs to know about.