90 lines
5.1 KiB
Markdown
90 lines
5.1 KiB
Markdown
# Handoff — the last two raylib ports
|
|
|
|
Two examples, `text_codepoints_loading` and `textures_image_processing`, ported into
|
|
`examples/`. This file is the running record: what is done, what was decided without being
|
|
able to ask, and what is still open. `../PORTING.md` has the findings that outlive the port —
|
|
its last section, "Porting the raylib examples — the last two" — and this file has the
|
|
state of the work.
|
|
|
|
## Status — done
|
|
|
|
- [x] `examples/text-codepoints-loading.flan` — builds
|
|
- [x] `examples/textures-image-processing.flan` — builds
|
|
- [x] `test/programs/raylib-codepoints.flan` and `test/programs/raylib-image-processing.flan`,
|
|
both in the acceptance table, both gated on libraylib, both run plain and at `-O0`
|
|
- [x] `../PORTING.md` section for this round
|
|
- [x] `dune test --root .` green
|
|
|
|
Four commits, each one a working state:
|
|
|
|
1. the plan and the open question (this file's first version)
|
|
2. `PixelFormat`, the one binding this round added
|
|
3. the image-processing example and its headless case
|
|
4. the codepoints example and its headless case
|
|
|
|
## Open questions for the author
|
|
|
|
1. **Vendor `DotGothic16-Regular.ttf`?** `text_codepoints_loading` draws Japanese, and
|
|
there is no CJK font in this tree. The font is SIL OFL 1.1 and therefore
|
|
redistributable, but it is 2 MB of binary in a repository whose only binary asset is a
|
|
1 KB PNG, and that is a call about the repository rather than about the port. The
|
|
example works either way: it looks for
|
|
`examples/resources/DotGothic16-Regular.ttf`, and if it is not there raylib hands back
|
|
the default font, the kana draw as boxes, and the program says on screen why. Drop the
|
|
TTF in and the glyphs appear with nothing else to change. `~/Repositories/raylib/examples/text/resources/`
|
|
has the file and its OFL notice.
|
|
|
|
2. **`lib/cimport.ml`'s `agrees` promises an arm it does not have.** The comment at
|
|
`lib/cimport.ml:1291` lists, among the differences that are "expected and are not
|
|
reported", *"a `(Ptr T)` where the header says `T *` and the hand-written line chose
|
|
something more specific"*. The function implements the enum-against-i32 arm and nothing
|
|
else. That missing arm is the only thing standing between this round's two refused
|
|
bindings and ordinary binding work — see `../PORTING.md` §A.1 and §A.2, which have the
|
|
exact declarations and the exact error. **Not built: it is a compiler change and the
|
|
freeze is on.** It is small and it is well specified, and it is the thing to do first if
|
|
these two ports are ever revisited.
|
|
|
|
3. The image-processing port keeps the C's `LoadImageColors` → `UpdateTexture` round trip
|
|
even though `(.data im-copy)` is the same bytes and already the right type. Kept
|
|
because it is what the C does and because nothing else in the corpus exercises that
|
|
pair. If you would rather the example were the short version, the comment on
|
|
`reload-texture` says exactly what to delete.
|
|
|
|
## Deviations from the upstream C, all deliberate, all commented in place
|
|
|
|
- **Neither asset is vendored.** `parrots.png` has no licence at all in raylib's own
|
|
LICENSE.md, so the image-processing example generates its picture. The generated image is
|
|
asymmetric in both axes and has hard edges on purpose — a symmetric one makes the two
|
|
flips indistinguishable and the blur invisible.
|
|
- **The duplicate removal is a build-up, not a compaction.** The C's shift-the-tail-down
|
|
loop reads one element past the end of its allocation, which C tolerates and Flan's
|
|
bounds check does not.
|
|
- **The codepoint cursor clamps at both ends.** The C's runs off both.
|
|
- **`GetCodepointPrevious` is not called**, because it cannot be: a Flan string reaches C
|
|
as a NUL-terminated copy and that function reads backwards out of the pointer. Four
|
|
lines of continuation-byte walking replace it, and the headless case pins them against
|
|
`LoadCodepoints`.
|
|
- **The UP key in image processing wraps to 7 and not to 8**, which is the C's own
|
|
off-by-one, left as it is so that the port and the example it claims to be do not
|
|
disagree.
|
|
|
|
## Things a next lane should know
|
|
|
|
- `examples/` is **not** compiled by `dune test`. `test/dune` globs it so that imports
|
|
resolve, nothing more. `flan build <example>` is the only proof an example compiles, and
|
|
it is worth running on all of them after any change to `vendor/raylib`.
|
|
- The header check in `vendor/raylib/headers` runs on **every ordinary build**, not only on
|
|
`flan generate-c`. A hand-written `declare-c` that disagrees with `raylib-5.5.h` therefore
|
|
breaks every build in the tree, not just regeneration. That is what makes open question 2
|
|
a blocker rather than an inconvenience.
|
|
- `(string (slice b off (len b)))` is the idiom for a C `char *` cursor into the middle of a
|
|
string, and it costs nothing. It is correct for every entry point that reads forwards and
|
|
wrong for every one that reads backwards.
|
|
- `slice-from-ptr` is how a raylib pointer-plus-count becomes something with a length. Both
|
|
new test programs lean on it.
|
|
|
|
## Log
|
|
|
|
- Started from `957ba07` on `dev-loop`. The worktree came up on a much older commit
|
|
(`2c232dd`, no `examples/` directory at all) and was reset onto the branch tip first.
|