Progress on documentation

docs/Readme.md

@@ -14,12 +14,20 @@ Much of the data structures within the context struct are not fixed-capacity all
 
 The library supports being used in a dynamically loaded module. If its hot-reloaded simply make sure to call this procedure with a reference to the backing allocator provided during startup as all dynamic containers tend to lose a proper reference to the allocator's procedure.
 
-Call clear_atlas_region_caches & clear_shape_cache to reset the library's shape and glyph cache state to force a re-render.
+Call `clear_atlas_region_caches` & `clear_shape_cache` to reset the library's shape and glyph cache state to force a re-render.
 
 ### shutdown
 
 Release resources from the context.
 
+### clear_atlas_region_caches
+
+Clears the LRU caches of regions A-D of the Atlas & sets their next_idx to 0. Effectively will force a re-cache of all previously rendered glyphs. Shape configuration for the glyph will remain unchanged unless clear_shape_cache is also called.
+
+### clear_shape_cache
+
+Clears the LRU cache of the shaper along with clearing all existing storage entries. Effectively will force a re-cache of previously cached text shapes (Does not recache their rendered glyphs).
+
 ### load_font
 
 Will load an instance of a font. The user needs to load the file's bytes themselves, the font entry (Entry :: struct) will by tracked by the library. The user will be given a font_id which is a direct index for the entry in the tracked array.
@@ -28,23 +36,55 @@ Will load an instance of a font. The user needs to load the file's bytes themsel
 
 Will free an entry, (parser and shaper resources also freed)
 
-## Scoping Context interface
+## Shaping
 
-These are a set of push & pop pairs of functions that operator ont he context's stack containers. They are used with the draw_shape and draw_text procedures. This mainly for quick scratch usage where the user wants to directly compose a large amount of text without having a UI framework directly handle the text backend.
+Ideally the user should track the shapes themselves in a time-scale beyond the per-frame draw call. This avoids having to do caching/lookups of the shope.
 
-* font
-* font_size
-* colour: Linear colour.
-* view: Width and height of the 2D area the text will be drawn within.
-* position: Uses relative positioning will offset the incoming position by the given amount.
-* scale: Uses relative scaling, will scale the procedures incoming scale by the given amount.
-* zoom: Affects scaling, will scale the procedure's incoming font size & scale based on an *UX canvas camera's* notion of it.
+### shape_text
 
-Procedure types:
+Will shape the text using the `shaper_proc` arugment (user overloadable). Shape will be cached by the library.
 
-* `scope_<stack_option>`: push with a defer pop
-* `push_<stack_option>`
-* `pop_<stack_option>`
+### shape_text_uncached
+
+Will shape the text using the `shaper_proc` arugment (user overloadable).
+Shape will NOT be cached by the library. Use this if you want to roll your own solution for tracking shapes.
+
+## Draw list generation
+
+### get_draw_list
+
+Get the enqueded draw_list (vertices, indices, and draw call arrays) in its entirety.
+By default, if get_draw_list is called, it will first call `optimize_draw_list` to optimize the draw list's calls for the user. If this is undesired, make sure to pass `optimize_before_returning = false` in the arguments.
+
+### get_draw_list_layer
+
+Get the enqueued draw_list for the current "layer".
+A layer is considered the slice of the `Draw_List`'s content from the last call to `flush_draw_list_layer` onward.
+By default, if `get_draw_list_layer` is called, it will first call `optimize_draw_list` for the user to optimize the slice (exlusively) of the draw list's draw calls. If this is undesired, make sure to pass `optimize_before_returning = false` in the arguments.
+
+The draw layer offsets are cleared with `flush_draw_list`
+
+### flush_draw_list
+
+Will clear the draw list and draw layer offsets.
+
+### flush_draw_list_layer
+
+Will update the draw list layer with the latest offset based on the current lenght of the draw list vertices, indices, and calls arrays.
+
+## Metrics
+
+### measure_shape_size
+
+This provide's the shape size scaled down by the ctx.px_scale to get intended usage size. Size is equivalent to `measure_text_size`.
+
+### measure_text_size
+
+Provides a Vec2 the width and height occupied by the provided text string. The y is measured to be the the largest glyph box bounds height of the text. The width is derived from the `end_cursor_pos` field from a `Shaped_Text` entry.
+
+### get_font_vertical_metrics
+
+A wrapper for `parser_get_font_vertical_metrics`. Will provide the ascent, descent, and line_gap for a font entry.
 
 ## Miscellaneous
 
@@ -62,62 +102,68 @@ Does nothing if view is 1 or 0
 
 This is used by draw via view relative space procedures to normalize it to the intended space for the render pass.
 
-## resolve_draw_px_size
+### resolve_draw_px_size
 
-Used to constrain the px_size used in draw calls.
+Used to constrain the px_size used in `resolve_zoom_size_scale`.
 
 The view relative space and scoping stack-based procedures support zoom. When utilizing zoom their is a nasty jitter that will occur if the user smoothly goes across different font sizes because the spacing can drastically change between even and odd font-sizes. This is applied to enforce the font sticks to a specific interval.
 
-For the provided procedures that utilize it, they reference the context's zoom_px_interval. It can be set with `set_zoom_px_interval` and the default value is 2.
+The library uses the context's zoom_px_interval as the reference interval in the draw procedures. It can be set with `set_zoom_px_interval` and the default value is 2.
 
-## resolve_zoom_size_scale
+### resolve_zoom_size_scale
 
+Provides a way to get a "zoom" on the font size and scale, similar conceptually to a canvas UX zoom
+Does nothing when zoom is 1.0
 
+Uses `resolve_draw_px_size` to constrain which font size is used for the zoom.
 
-### configure_snap
+### set_alpha_scalar
 
-You'll find this used immediately in draw_text it acts as a way to snap the position of the text to the nearest pixel for the width and height specified.
+This is an artifact feature of the current shader, it *may* be removed in the future... Increasing the alpha of the colour draw with above 1.0 increases the edge contrast of the glyph shape.
 
-If snapping is not desired, set the snap_width and height before calling draw_text to 0.
+For the value to be added to the colour, the alph of the text must already be at 1.0 or greater.
 
+### set_px_scalar
 
-### set_color
+This another "super-scalar" applied to rendering glyphs. In each draw procedure the following is computed before passing the values to the shaper and draw list generation passes:
 
-Sets the color to utilize on `Draw_Call`s for FrameBuffer.Target or .Target_Uncached passes
+```go
+target_px_size    := px_size * ctx.px_scalar
+target_scale      := scale   * (1 / ctx.px_scalar)
+target_font_scale := parser_scale( entry.parser_info, target_px_size )
+```
 
-### get_draw_list
+Essentially, `ctx.px_scalar` is used to upscale the px_size by its value and then downscale the render target scale back the indended size. Doing so provides better shape positioning and futher improves text hinting. The downside is that small text tends to become more jagged (as its really hitting the limits of of how well the shader can blend those edges at that resolution).
 
-Get the enqueded draw_list (vertices, indices, and draw call arrays) in its entirety.
-By default, if get_draw_list is called, it will first call `optimize_draw_list` to optimize the draw list's calls for the user. If this is undesired, make sure to pass `optimize_before_returning = false` in the arguments.
+This will most likely be preserved with future shader upgrades, however it will most likely not be as necessary as it is right now to achieve crisp text.
 
-###  get_draw_list_layer
+### set_zoom_px_interval
 
-Get the enqueued draw_list for the current "layer".
-A layer is considered the slice of the `Draw_List`'s content from the last call to `flush_draw_list_layer` onward.
-By default, if `get_draw_list_layer` is called, it will first call `optimize_draw_list` for the user to optimize the slice (exlusively) of the draw list's draw calls. If this is undesired, make sure to pass `optimize_before_returning = false` in the arguments.
+Used with by draw procedures with `resolve_draw_px_size` & `resolve_zoom_size_scale`. Provides the interval to use when constraining the px_size to a specific set of values when using zoom scaling.
 
-The draw layer offsets are cleared with `flush_draw_list`
+### set_snap_glyph_shape_position
 
-### flush_draw_list
+During the shaping pass, the position of each glyph can be rounded up to the integer to (ussually) allow better hinting.
 
-Will clear the draw list and draw layer offsets.
+### set_snap_glyph_render_height
 
-### flush_draw_list_layer
+During the draw list generation pass, the position of each glyph when blitting to atlas can have teh quad size rounded up to the integer.
+Can yield better hinting but may significantly stretch the glyphs at small scales.
 
-Will update the draw list layer with the latest offset based on the current lenght of the draw list vertices, indices, and calls arrays.
+## Scope Stack
 
-### measure_text_size
+These are a set of push & pop pairs of functions that operator ont he context's stack containers. They are used with the draw_shape and draw_text procedures. This mainly for quick scratch usage where the user wants to directly compose a large amount of text without having a UI framework directly handle the text backend.
 
-Provides a Vec2 the width and height occupied by the provided text string. The y is measured to be the the largest glyph box bounds height of the text. The width is derived from the `end_cursor_pos` field from a `Shaped_Text` entry.
+* font
+* font_size
+* colour: Linear colour.
+* view: Width and height of the 2D area the text will be drawn within.
+* position: Uses relative positioning will offset the incoming position by the given amount.
+* scale: Uses relative scaling, will scale the procedures incoming scale by the given amount.
+* zoom: Affects scaling, will scale the procedure's incoming font size & scale based on an *UX canvas camera's* notion of it.
 
-### get_font_vertical_metrics
+Procedure types:
 
-A wrapper for `parser_get_font_vertical_metrics`. Will provide the ascent, descent, and line_gap for a font entry.
-
-### clear_atlas_region_caches
-
-Clears the LRU caches of regions A-D of the Atlas & sets their next_idx to 0. Effectively will force a re-cache of all previously rendered glyphs. Shape configuration for the glyph will remain unchanged unless clear_shape_cache is also called.
-
-### clear_shape_cache
-
-Clears the LRU cache of the shaper along with clearing all existing storage entries. Effectively will force a re-cache of previously cached text shapes (Does not recache their rendered glyphs).
+* `scope_<stack_option>`: push with a defer pop
+* `push_<stack_option>`
+* `pop_<stack_option>`

docs/guide_.architecturemd

@@ -0,0 +1,28 @@
+# Architecture
+
+The purpose of this library to really allieviate four issues with one encapsulation:
+
+* font parsing
+* text codepoint shaping
+* glyph shape triangulation
+* glyph draw-list generation
+
+Shaping text, getting metrics for the glyphs, triangulating glyphs, and anti-aliasing their render are expensive todo per frame. So anything related to that compute that may be cached, will be.
+
+There are two cache types used:
+
+* shape cache (shape_cache.state)
+* atlas region cache (Atlas_Region.state)
+
+The shape cache stores all data for a piece of text that will be utilized in a draw call that is not dependent on a specific position & scale (and is faster to lookup vs compute per draw call). So far these are the text shaping itself, and per-glyph infos: atlas_lru_code (atlas key), atlas region resolution, & glyph bounds.
+The atlas region cache tracks what slots have glyphs rendered to the texture atlas. This essentially is caching of triangulation and super-sampling compute.
+
+All caching uses the [LRU.odin](../vefontcache/LRU.odin)
+
+## Codepaths
+
+## Library Lifetime
+
+## Draw List Generation
+
+The base draw list generation pipepline provided by the library allows the user to batch whatever the want into a single "layer". However 

docs/guide_backend.md

@@ -0,0 +1,7 @@
+# Backend Guide
+
+The end-user needs adapt this library for hookup into their own codebase. As an example they may see the [examples](../examples/) and [backend](../backend/) for working code of what this guide will go over.
+
+When rendering text, the two products the user has to deal with: The text to draw and their "layering". Similar to UIs text should be drawn in layer batches, where each layer can represent a pass on some arbitrary set of distictions between the other layers.
+
+