summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorVito Caputo <vcaputo@pengaru.com>2022-04-25 10:35:33 -0700
committerVito Caputo <vcaputo@pengaru.com>2022-04-25 10:35:33 -0700
commitd778d22faecb4b46fc06fab5f98ad48db84f2b7d (patch)
treed9a4f918f75454922203d76a59a0ae3f6f99c70a
parent3427eefac9cf38ac3fa2635c69bb3f0693700cf8 (diff)
doc: fix some typos/inconsistencies in HACKING.txt
Just some fixups after a quick review
-rw-r--r--HACKING.txt41
1 files changed, 22 insertions, 19 deletions
diff --git a/HACKING.txt b/HACKING.txt
index 35921ad..cbf65cb 100644
--- a/HACKING.txt
+++ b/HACKING.txt
@@ -76,7 +76,7 @@ Hacking on rototiller / libtil:
After successfully building rototiller with the CLI frontend, an
executable will be at "src/rototiller" in the build tree. If the steps
- above were followed verbatim, that would be at `build/src/rototiller`.
+ above were followed verbatim, that would be at "build/src/rototiller".
Quickly testing modules via the CLI frontend:
@@ -128,14 +128,17 @@ Hacking on rototiller / libtil:
For most modules these members are simply used as provided, and
there's no need to manipulate them. For simple non-threaded cases only
- the "buf" and "frame_{width,height}" members are required, with "stride"
- or "pitch" becoming important for algorithms directly manipulating buf's
+ the "buf" and "{width,height}" members are required, with "stride" or
+ "pitch" becoming important for algorithms directly manipulating buf's
memory contents to properly address rows of pixels since fragments may
be discontiguous in buf at row boundaries for a variety of reasons.
- When using threaded rendering, the "{width,height}" members become
- important as they describe a fragment's dimensions within the frame being
- rendered.
+ When using threaded rendering, the "frame_{width,height}" members
+ become important as they describe a fragment's full-frame dimensions,
+ while "{width,height}" describe the specific fragment within the frame
+ being rendered by render_fragment(). In non-threaded scenarios these
+ members have the same values, but threading employs subfragmenting the
+ frame into independent fragments potentially rendered concurrently.
The module_render() function prototype is declared within the
"til_module_t" struct in "src/til.h" as:
@@ -271,10 +274,10 @@ Hacking on rototiller / libtil:
which is potentially relevant for threaded renderers. The "unsigned
cpu" parameter supplied to render_fragment() will always be < this
n_cpus value, and the two are intended to complement eachother. When
- creating the context, one may allocate per-cpu cache-aligned in
+ creating the context, one may allocate per-cpu cache-aligned space in
n_cpus quantity. Then the render_fragment() function would address
- the per-cpu space using the cpu parameter as an index into the n_cpus
- sized allocation.
+ this per-cpu space using the cpu parameter as an index into the
+ n_cpus sized allocation.
This is often ignored.
void *setup:
@@ -286,7 +289,7 @@ Hacking on rototiller / libtil:
As mentioned above in describing the rendering function, this is
entirely optional. One may create 100% valid modules implementing only
- the render_fragment().
+ the render_fragment() function.
Runtime-configurable rendering:
@@ -395,14 +398,14 @@ Hacking on rototiller / libtil:
}
- In the above example a the minimal module now has a "foobar" boolean
+ In the above example the minimal module now has a "foobar" boolean
style setting supporting the values "on" and "off". It may be specified
at runtime to rototiller (or any other frontend) via the commandline
argument:
- "--module=minimal,foobar=true"
+ "--module=minimal,foobar=on"
- And if the "foobar=true" setting were omitted from the commandline, in
+ And if the "foobar=on" setting were omitted from the commandline, in
rototiller's CLI frontend an interactive setup dialog would occur, i.e:
Foobar configurable setting:
@@ -412,7 +415,7 @@ Hacking on rototiller / libtil:
Much can be said on the subject of settings, this introduction should
be enough to get started. Use the existing modules as a reference on how
- to implement sttings. The sparkler modules in particular has one of the
+ to implement settings. The sparkler module in particular has one of the
more complicated setup() functions involving dependencies where some
settings become expected and described only if others are enabled.
@@ -424,10 +427,10 @@ Hacking on rototiller / libtil:
Note how the minimal_setup_t instance returned by setup() in res_setup
is subsequently supplied to minimal_create_context() in its setup
- parameter. In the previous Stateful rendering example, this setup
+ parameter. In the previous "Stateful rendering" example, this setup
parameter was ignored as it would always be NULL lacking any setup()
function. But here we use it to retrieve the "foobar" value wired up by
- the minimal_setup() function supplied for minimal_module.setup.
+ the minimal_setup() function supplied as minimal_module.setup.
Threaded rendering:
@@ -435,7 +438,7 @@ Hacking on rototiller / libtil:
Rototiller deliberately abstains from utilizing any GPU hardware-
acceleration for rendering. Instead, all rendering is done using the CPU
programmed simply in C, without incurring a bunch of GPU API complexity
- like OpenGL/Direct3D or any need manage GPU resources.
+ like OpenGL/Direct3D or any need to manage GPU resources.
Modern systems tend to have multiple CPU cores, enabling parallel
execution similar to how GPUs employ multiple execution units for
@@ -460,9 +463,9 @@ Hacking on rototiller / libtil:
What's special here is the res_fragmenter parameter. This is where
your module is expected to provide a fragmenter function rototiller will
- call repeatedly while splitting up the frame's fragment being rendered
+ call repeatedly while breaking up the frame's fragment being rendered
into smaller subfragments for passing to the module's render_fragment()
- in place of the larger frame's fragment.
+ in place of the larger frame's whole fragment.
This effectively gives modules control over the order, quantity, size,
and shape, of individually rendered subfragments. Logically speaking,
© All Rights Reserved