@geastack/core 0.1.23

package/include/graphics/font.h

@@ -0,0 +1,122 @@
+#pragma once
+
+#include <cstdint>
+
+namespace gea::framework::graphics {
+
+struct Glyph {
+	int codepoint = 0;
+	int sourceX = 0;
+	int sourceY = 0;
+	int width = 0;
+	int height = 0;
+	int advance = 0;
+	int bearingX = 0;
+	int bearingY = 0;
+};
+
+class Font {
+public:
+	virtual ~Font() = default;
+
+	virtual bool valid() const = 0;
+	virtual int sizePx() const = 0;
+	virtual int lineHeight() const = 0;
+	virtual int ascender() const = 0;
+	virtual bool glyph(int codepoint, Glyph *out) const = 0;
+	virtual std::uint8_t coverage(const Glyph &glyph, int row, int col) const = 0;
+};
+
+class BitmapFont : public Font {
+public:
+	static constexpr int kFirstCodepoint = 0x20;
+	static constexpr int kLastCodepoint = 0x7e;
+	static constexpr int kGlyphCount = kLastCodepoint - kFirstCodepoint + 1;
+	static constexpr int kWidth = 8;
+	static constexpr int kHeight = 16;
+
+	bool valid() const final;
+	int sizePx() const final;
+	int lineHeight() const final;
+	int ascender() const final;
+	bool glyph(int codepoint, Glyph *out) const final;
+	std::uint8_t coverage(const Glyph &glyph, int row, int col) const final;
+
+	// Takes a CODEPOINT, not a byte. Typed `char` this silently truncated every
+	// non-ASCII glyph: a caller decoding UTF-8 properly still narrowed U+2014 to
+	// one byte, and a caller not decoding at all handed over three bytes in turn
+	// and got three substitution glyphs. `rowsForCodepoint` already substitutes
+	// out-of-range codepoints, which is the whole of the fallback policy.
+	const std::uint8_t *glyphRows(int codepoint) const;
+
+protected:
+	virtual const std::uint8_t *rowsForCodepoint(int codepoint) const = 0;
+};
+
+class BitmapFont8x16 final : public BitmapFont {
+public:
+	static const BitmapFont8x16 &instance();
+
+private:
+	const std::uint8_t *rowsForCodepoint(int codepoint) const final;
+
+	static const std::uint8_t glyphs[kGlyphCount][kHeight];
+};
+
+struct RasterizedFontData {
+	int id = 0;
+	int sizePx = 0;
+	int lineHeight = 0;
+	int ascender = 0;
+	int descender = 0;
+	int glyphCount = 0;
+	const Glyph *glyphs = nullptr;
+	int atlasWidth = 0;
+	int atlasHeight = 0;
+	const std::uint8_t *atlas = nullptr;
+	// Bits per atlas pixel. 8 = one coverage byte per pixel (the default, and
+	// what runtime-rasterized fonts always produce). 2 = four pixels per byte,
+	// baked offline for panels that can only show four gray levels; rows are
+	// byte-aligned (stride = (atlasWidth + 3) / 4) and the leftmost pixel of a
+	// byte sits in the most significant bit pair.
+	int atlasBits = 8;
+};
+
+class RasterizedFont final : public Font {
+public:
+	RasterizedFont() = default;
+	explicit RasterizedFont(const RasterizedFontData *data);
+
+	bool valid() const final;
+	int sizePx() const final;
+	int lineHeight() const final;
+	int ascender() const final;
+	bool glyph(int codepoint, Glyph *out) const final;
+	std::uint8_t coverage(const Glyph &glyph, int row, int col) const final;
+	const RasterizedFontData *data() const { return data_; }
+
+private:
+	const RasterizedFontData *data_ = nullptr;
+};
+
+class FontRegistry {
+public:
+	static RasterizedFont rasterized(int fontId);
+	static RasterizedFont rasterizedFamily(int familyId, int sizePx);
+	static const BitmapFont8x16 &bitmap8x16();
+	static int familyId(const char *family);
+	static const char *familyName(int familyId);
+};
+
+namespace generated {
+
+const RasterizedFontData *lookupFont(int fontId);
+const RasterizedFontData *lookupFontForFamily(int familyId, int sizePx);
+int lookupFontFamily(const char *family);
+const char *lookupFontFamilyName(int familyId);
+const std::uint8_t *lookupRuntimeTtfFontForFamily(int familyId, unsigned long *length);
+void ensureLinked();
+
+}  // namespace generated
+
+}  // namespace gea::framework::graphics

package/include/i2c.h

@@ -0,0 +1,20 @@
+#pragma once
+
+namespace gea::platform::i2c {
+
+class Bus {
+public:
+	using NativeHandle = void *;
+
+	static Bus primary();
+
+	bool available() const { return handle_ != nullptr; }
+	NativeHandle nativeHandle() const { return handle_; }
+
+private:
+	explicit Bus(NativeHandle handle) : handle_(handle) {}
+
+	NativeHandle handle_ = nullptr;
+};
+
+}  // namespace gea::platform::i2c

package/include/image.h

@@ -0,0 +1,156 @@
+#pragma once
+
+#include "pixel.h"
+
+#include <cstdint>
+
+#if GEA_EMBEDDED_SINGLE_THREAD_IMAGE_STORE
+namespace gea::framework::graphics {
+struct ImageStoreMutex {
+	void lock() noexcept {}
+	void unlock() noexcept {}
+};
+}  // namespace gea::framework::graphics
+#else
+#include <mutex>
+#endif
+
+namespace gea::framework::graphics {
+
+#if !GEA_EMBEDDED_SINGLE_THREAD_IMAGE_STORE
+using ImageStoreMutex = std::mutex;
+#endif
+
+// Decoded-image slot pool. Slots are lazy (pixel buffers allocated only on
+// decode), so a larger pool costs almost nothing until filled. 96 lets a
+// tile-grid app (maps) keep ~4 screens of decoded tiles resident in PSRAM for
+// instant pan-back, on top of its persistent SD cache. ~128 KiB/tile (RGB565
+// 256x256) when full → ~12 MiB; the P4 has ample PSRAM.
+inline constexpr int kImageMax = 96;
+
+enum class ImageFit {
+	Fill = 0,
+	Contain = 1,
+	Cover = 2,
+	None = 3,
+	ScaleDown = 4,
+};
+
+enum class ImageFormat {
+	Unknown = 0,
+	Jpeg = 1,
+	Png = 2,
+	Gif = 3,
+};
+
+struct ImageSlot {
+	int width = 0;
+	int height = 0;
+	int frameCount = 0;
+	ImageFormat format = ImageFormat::Unknown;
+	int loopCount = 0;
+	int currentFrame = 0;
+	bool playing = false;
+	int elapsedMs = 0;
+	int currentDelayMs = 0;
+
+	// Decoded pixels in this target's native framebuffer format (RGB565 on
+	// esp32/geaos, RGBA8888 on iOS) — set at compile time by pixel::native_t.
+	// Full colour on RGBA8888 targets (the decoder's 8-bit channels are kept, not
+	// quantized to 565), so native UIImageView presents stills at full colour.
+	pixel::native_t *pixels = nullptr;
+	std::uint8_t *alpha = nullptr;
+	bool ownsPixels = false;
+
+	void *gifDecoder = nullptr;
+	std::uint8_t *gifData = nullptr;
+	int gifDataLength = 0;
+
+	// Deferred decode (decodeDeferred): the encoded bytes live at a stable
+	// address (embedded flash assets); only the header was probed for dims.
+	// The first pixel access (record time) materializes the decode.
+	const std::uint8_t *deferredData = nullptr;
+	int deferredLength = 0;
+	// stbi_info reports the encoded channel count while probing dimensions.
+	// Preserve whether the source has no alpha channel so materialization can
+	// discard the synthetic all-255 alpha plane and use the opaque blit path.
+	bool deferredOpaque = false;
+};
+
+class ImageStore {
+public:
+	static ImageStore &instance();
+
+	int decode(const std::uint8_t *data, int length, int preferredSlot = -1);
+	int decodeOpaque(const std::uint8_t *data, int length, int preferredSlot = -1);
+	// Deferred decode for encoded bytes at a STABLE address (embedded flash
+	// assets): probes only the header for dimensions (layout needs them at
+	// mount) and decodes on first pixel access (record time). Cuts boot-time
+	// decoding to the icons actually visible. GIFs decode eagerly.
+	int decodeDeferred(const std::uint8_t *data, int length, int preferredSlot = -1);
+	// Materialize ONE pending deferred decode (idle-time pre-decode). Returns
+	// false when none are pending. Lets the frame loop drain deferred slots
+	// during idle frames so a later first-draw (e.g. switching weather cities)
+	// doesn't bunch every decode into a single visible hitch.
+	bool materializeOneDeferred();
+	// Register an externally-owned native-format pixel buffer. `takeOwnership`
+	// transfers ownership to the store (freed on dispose) — used by the iOS
+	// camera capture, which hands over a freshly-allocated RGBA8888 still.
+	int registerBuffer(pixel::native_t *pixels, int width, int height, int preferredSlot = -1, bool takeOwnership = false);
+
+	int width(int id) const;
+	int height(int id) const;
+	int frameCount(int id) const;
+	bool isAnimated(int id) const;
+	ImageFormat format(int id) const;
+	void setPlaying(int id, bool playing);
+	bool playing(int id) const;
+	void seek(int id, int frame);
+	int currentFrame(int id) const;
+	bool advance(int id, int deltaMs);
+	const pixel::native_t *framePixels(int id, int frame) const;
+	const pixel::native_t *currentPixels(int id) const;
+	const std::uint8_t *currentAlpha(int id) const;
+	void dispose(int id);
+	void disposeAll();
+	ImageFormat detectFormat(const std::uint8_t *data, int length) const;
+
+private:
+	ImageSlot *slot(int id);
+	const ImageSlot *slot(int id) const;
+	int findFreeSlot(int preferredSlot) const;
+	int decodeWithHint(const std::uint8_t *data, int length, int preferredSlot, bool opaqueHint);
+	// Materializes a deferred decode in place (no-op when already decoded).
+	void materializeDeferred(int id) const;
+	int decodeGif(ImageSlot &image, const std::uint8_t *data, int length);
+	int decodeStatic(ImageSlot &image, const std::uint8_t *data, int length, bool opaqueHint);
+#if defined(GEA_EMBEDDED_ROM_TJPGD) && GEA_EMBEDDED_ROM_TJPGD
+	// Low-memory JPEG decode via the ESP32 ROM tinyjpeg decompressor (descales
+	// large covers so they fit the fragmented PSRAM). Fills `image`, returns 0/-1.
+	int decodeJpegTjpgd(ImageSlot &image, const std::uint8_t *data, int length);
+#endif
+	int decodeNextGifFrame(ImageSlot &image);
+	// dispose() body without taking slotMutex_ (callers hold it).
+	void disposeLocked(int id);
+
+ public:
+	// Rotate a SQUARE opaque image 90deg so its pixels match the portrait
+	// panel orientation (panel-native landscape rendering: tiles rotate once
+	// at decode instead of the display rotating every frame). No-op for
+	// non-square or alpha-carrying images.
+	bool rotate90(int id);
+
+ private:
+
+	ImageSlot images_[kImageMax]{};
+	bool used_[kImageMax]{};
+	// Guards slot ALLOCATION and DISPOSAL only (reservation-style): the async
+	// tile loader decodes on the second core while the frame task blits and
+	// evicts. A decode reserves its slot under the lock, then fills it
+	// unlocked — the slot id isn't visible to the app until the loader
+	// delivers it, so nothing reads a half-decoded slot. Pixel READS of
+	// already-delivered slots stay lock-free.
+	mutable ImageStoreMutex slotMutex_;
+};
+
+}  // namespace gea::framework::graphics

package/include/imu.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <stdint.h>
+
+namespace gea::platform::sensors {
+
+class Accelerometer {
+public:
+	static void init();
+	static void close();
+	static void calibrateBias();
+	static int tiltX();
+	static int tiltY();
+	static double accelerationX();
+	static double accelerationY();
+	static double accelerationZ();
+	static double gyroscopeX();
+	static double gyroscopeY();
+	static double gyroscopeZ();
+	static void setWebTilt(int x, int y);
+};
+
+}  // namespace gea::platform::sensors

package/include/input.h

@@ -0,0 +1,33 @@
+#pragma once
+
+namespace gea::framework::input {
+
+// Sets a one-shot "back button pressed" flag. Called from the platform
+// launcher-button task (BOOT short press on ESP32) and from the per-app
+// application's `_settings_toggle()` entry stub.
+void pressBackButton();
+
+// Reads and clears the flag. Returns true if there was a pending press.
+// Polled from the launcher's rAF loop; when true and Settings is visible,
+// the launcher closes Settings.
+bool consumeBackButton();
+
+// Adds rotary encoder detents to the pending input delta. Called by platform
+// input tasks; drained by the runtime frame loop and dispatched through the UI
+// tree as a normal bubbling `rotary` event.
+void queueRotaryDelta(int delta);
+
+// Reads and clears the pending rotary delta. Returns 0 if there is no pending
+// movement.
+int consumeRotaryDelta();
+
+// Queues a key press (web keyCode, e.g. 38/40 for ArrowUp/ArrowDown) from a
+// platform input task — hardware buttons on boards without touch. Drained by
+// the runtime frame loop and dispatched through the UI tree as a bubbling
+// `keydown` event. keyCode 0 is ignored.
+void queueKeyDown(int keyCode);
+
+// Reads and clears the oldest pending key press. Returns 0 when none pending.
+int consumeKeyDown();
+
+}  // namespace gea::framework::input

package/include/memory.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace gea::framework::memory {
+
+class Allocator {
+public:
+	static void *allocatePreferSpiram(std::size_t size, std::size_t alignment = alignof(std::max_align_t));
+	static void *reallocatePreferSpiram(void *ptr, std::size_t size);
+	static void free(void *ptr) noexcept;
+};
+
+}  // namespace gea::framework::memory
+
+namespace gea::platform::memory {
+
+class Memory {
+public:
+	static std::uint32_t internalFree();
+	static std::uint32_t internalLargestFreeBlock();
+	static std::uint32_t internalMinimumFree();
+	static std::uint32_t psramFree();
+	static std::uint32_t currentTaskStackHighWaterMark();
+	static std::uint32_t geaMainStackBytes();
+	static std::uint32_t geaInitStackBytes();
+	static std::uint32_t appFrameStackWords();
+	static std::uint32_t appFrameStackBytes();
+	static std::uint32_t displayFlushConfiguredRows();
+	static std::uint32_t displayFlushConfiguredDepth();
+	static std::uint32_t displayFlushBufferMaxBytes();
+	static std::uint32_t displayFlushRows();
+	static std::uint32_t displayFlushDepth();
+	static std::uint32_t displayFlushBufferBytes();
+
+	// Holds `bytes` of internal, DMA-capable RAM out of the general heap and hands
+	// back an opaque reserve, so a later allocation that MUST be internal -- a
+	// display bus, a DMA descriptor ring -- still finds a block after code that
+	// runs earlier has taken what it wants. nullptr when the reserve could not be
+	// taken; releaseInternalDma() gives it back. A platform that does not
+	// distinguish internal memory returns nullptr and the caller carries on.
+	//
+	// Deliberately a real method on the platform API rather than a weak hook: a
+	// weak *undefined* reference does not pull the defining object out of a static
+	// archive, so the hook-shaped version of this linked to null on every ESP32
+	// image and the reserve silently never happened.
+	static void *reserveInternalDma(std::size_t bytes);
+	static void releaseInternalDma(void *reserve);
+};
+
+}  // namespace gea::platform::memory