@geastack/core 0.1.38 → 0.1.40

package/include/image.h

@@ -3,6 +3,7 @@
 #include "pixel.h"
 
 #include <cstdint>
+#include <utility>
 
 #if GEA_EMBEDDED_SINGLE_THREAD_IMAGE_STORE
 namespace gea::framework::graphics {
@@ -26,7 +27,10 @@ using ImageStoreMutex = std::mutex;
 // 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;
+#ifndef GEA_EMBEDDED_MAX_IMAGES
+#define GEA_EMBEDDED_MAX_IMAGES 96
+#endif
+inline constexpr int kImageMax = GEA_EMBEDDED_MAX_IMAGES;
 
 enum class ImageFit {
 	Fill = 0,
@@ -61,6 +65,9 @@ struct ImageSlot {
 	pixel::native_t *pixels = nullptr;
 	std::uint8_t *alpha = nullptr;
 	bool ownsPixels = false;
+	// Registered by the app (registerBuffer): the app writes these pixels in
+	// place between frames, so the same pointer does not mean the same image.
+	bool mutablePixels = false;
 
 	void *gifDecoder = nullptr;
 	std::uint8_t *gifData = nullptr;
@@ -98,6 +105,11 @@ public:
 	// 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);
 
+	// True when `pixels` point into a registerBuffer() image, whose content the
+	// app rewrites in place. The present diff never treats such an image as
+	// unchanged from the previous frame.
+	bool pixelsMayChange(const pixel::native_t *pixels) const;
+
 	int width(int id) const;
 	int height(int id) const;
 	int frameCount(int id) const;
@@ -111,6 +123,10 @@ public:
 	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;
+	// Pins keep decoded pixels alive for nodes and retained render commands.
+	bool retain(int id);
+	void release(int id);
+	int idForPixels(const pixel::native_t *pixels) const;
 	void dispose(int id);
 	void disposeAll();
 	ImageFormat detectFormat(const std::uint8_t *data, int length) const;
@@ -142,6 +158,8 @@ private:
 
 	ImageSlot images_[kImageMax]{};
 	bool used_[kImageMax]{};
+	unsigned references_[kImageMax]{};
+	bool retired_[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
@@ -151,4 +169,32 @@ private:
 	mutable ImageStoreMutex slotMutex_;
 };
 
+// Copyable ownership for retained commands; raw pixel pointers alone do not
+// keep a decoded slot alive.
+class ImageReference {
+public:
+	ImageReference() = default;
+	explicit ImageReference(int id) : id_(ImageStore::instance().retain(id) ? id : -1) {}
+	ImageReference(const ImageReference &other) : ImageReference(other.id_) {}
+	ImageReference(ImageReference &&other) noexcept : id_(other.id_) { other.id_ = -1; }
+	~ImageReference() { ImageStore::instance().release(id_); }
+	ImageReference &operator=(const ImageReference &other) {
+		if (this != &other) {
+			ImageReference next(other);
+			std::swap(id_, next.id_);
+		}
+		return *this;
+	}
+	ImageReference &operator=(ImageReference &&other) noexcept {
+		if (this != &other) {
+			ImageStore::instance().release(id_);
+			id_ = other.id_;
+			other.id_ = -1;
+		}
+		return *this;
+	}
+private:
+	int id_ = -1;
+};
+
 }  // namespace gea::framework::graphics

package/include/input.h

@@ -27,7 +27,18 @@ int consumeRotaryDelta();
 // `keydown` event. keyCode 0 is ignored.
 void queueKeyDown(int keyCode);
 
+// Queue a release in the same ordered stream as key presses.
+void queueKeyUp(int keyCode);
+
+struct HardwareKeyEvent {
+  int keyCode;
+  bool pressed;
+};
+
+// Consume the oldest press or release without changing their order.
+bool consumeKeyEvent(HardwareKeyEvent &event);
+
 // Reads and clears the oldest pending key press. Returns 0 when none pending.
 int consumeKeyDown();
 
-}  // namespace gea::framework::input
+} // namespace gea::framework::input

package/include/platform/atomic_file.h

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <cerrno>
+#include <cstdint>
+#include <cstdio>
+#include <string>
+#include <sys/stat.h>
+#include <vector>
+
+namespace gea::platform::storage {
+
+struct FileOperations {
+  using Handle = std::FILE *;
+  Handle open(const std::string &path) {
+    return std::fopen(path.c_str(), "wb");
+  }
+  std::size_t write(Handle file, const std::vector<std::uint8_t> &bytes) {
+    return std::fwrite(bytes.data(), 1, bytes.size(), file);
+  }
+  bool close(Handle file) { return std::fclose(file) == 0; }
+  bool move(const std::string &from, const std::string &to) {
+    return std::rename(from.c_str(), to.c_str()) == 0;
+  }
+  bool remove(const std::string &path) {
+    return std::remove(path.c_str()) == 0 || errno == ENOENT;
+  }
+  bool destinationExists(const std::string &path) const {
+    struct stat info{};
+    return ::stat(path.c_str(), &info) == 0;
+  }
+};
+
+// POSIX/FAT can replace a destination with rename; SPIFFS requires moving it
+// aside first. Never truncate the current file while writing its replacement.
+// If the second rename fails, restore the backup (and retain it on disk even
+// when the filesystem also rejects that recovery rename).
+template <typename Operations>
+bool writeFileAtomically(const std::string &path,
+                         const std::vector<std::uint8_t> &bytes,
+                         Operations &files) {
+  const auto temporary = path + ".tmp";
+  auto file = files.open(temporary);
+  if (!file)
+    return false;
+  const bool written = files.write(file, bytes) == bytes.size();
+  const bool closed = files.close(file);
+  if (!written || !closed) {
+    files.remove(temporary);
+    return false;
+  }
+  if (files.move(temporary, path))
+    return true;
+  if (!files.destinationExists(path)) {
+    files.remove(temporary);
+    return false;
+  }
+  const auto backup = path + ".bak";
+  if (!files.remove(backup) || !files.move(path, backup)) {
+    files.remove(temporary);
+    return false;
+  }
+  if (!files.move(temporary, path)) {
+    files.move(backup, path);
+    files.remove(temporary);
+    return false;
+  }
+  files.remove(backup);
+  return true;
+}
+
+} // namespace gea::platform::storage

package/include/platform/file_cache.h

@@ -8,11 +8,14 @@ namespace gea::platform::storage {
 // targets without persistent storage transparently fall back to no caching.
 bool ensureMounted();
 
-// Register the platform's mount provider. A target with persistent storage (e.g.
-// a microSD card) calls this at startup with its mount function. Done via
+// Register the platform's mount provider. A target with persistent storage
+// (e.g. a microSD card) calls this at startup with its mount function. Done via
 // explicit registration rather than a weak symbol so the provider's translation
 // unit is guaranteed to be linked in (see the waveshare-p4-7 sdcard_mount.cpp,
 // wired from app_main).
 void setMountProvider(bool (*provider)());
 
-}  // namespace gea::platform::storage
+// Used by built-in flash storage only when no target-specific provider exists.
+void setFallbackMountProvider(bool (*provider)());
+
+} // namespace gea::platform::storage

package/include/power.h

@@ -6,6 +6,8 @@ class Power {
 public:
 	static bool init();
 	static int batteryPercent();
+	static bool charging();
+	static bool vibrate(double durationMs, int strength);
 };
 
 }  // namespace gea::platform::power

package/include/services/frame_scheduler.h

@@ -65,6 +65,12 @@ public:
 	static int frameIntervalMs();
 	static void setFrameRate(double fps);
 	static double frameRate();
+#if defined(ESP_PLATFORM) && defined(GEA_NATIVE_DEBUGGER) && GEA_NATIVE_DEBUGGER
+	// Debug cap applies to timer, TE and input-driven frames. Application FPS
+	// changes cannot exceed it; zero restores normal scheduling.
+	static void setDebuggerFrameRate(int fps);
+	static int debuggerFrameRate();
+#endif
 	static int nowMs();
 };
 

package/include/wifi.h

@@ -7,61 +7,76 @@
 namespace gea::framework::network {
 
 struct WifiNetwork {
-	std::string ssid;
-	int rssi = 0;
-	bool secured = false;
+  std::string ssid;
+  int rssi = 0;
+  bool secured = false;
 };
 
 class WifiDriver {
 public:
-	virtual ~WifiDriver() = default;
+  virtual ~WifiDriver() = default;
 
-	virtual bool init() = 0;
-	virtual bool enabled() const = 0;
-	virtual void setEnabled(bool enabled) = 0;
-	virtual bool connected() const = 0;
-	virtual int rssi() = 0;
-	virtual std::string ssid() = 0;
-	virtual std::string ip() const = 0;
-	virtual std::string mac() = 0;
-	virtual void configure(const std::string &ssid, const std::string &password) = 0;
-	virtual void scan() = 0;
-	virtual bool scanning() const = 0;
-	virtual int scanCount() const = 0;
-	virtual WifiNetwork networkAt(int index) const = 0;
-	virtual std::vector<WifiNetwork> scanResults() const = 0;
-	virtual void setWebState(bool connected, const char *ssid, const char *ip, int rssi);
-	virtual void setWebScanCount(int count);
-	virtual void setWebScanEntry(int index, const char *ssid, int rssi, bool secured);
+  virtual bool init() = 0;
+  virtual bool enabled() const = 0;
+  virtual void setEnabled(bool enabled) = 0;
+  virtual bool connected() const = 0;
+  virtual int rssi() = 0;
+  virtual std::string ssid() = 0;
+  virtual std::string ip() const = 0;
+  virtual std::string mac() = 0;
+  virtual void configure(const std::string &ssid,
+                         const std::string &password) = 0;
+  virtual bool startAccessPoint(const std::string &, const std::string &) {
+    return false;
+  }
+  virtual void stopAccessPoint() {}
+  virtual std::string accessPointMac() { return {}; }
+  virtual bool startCaptivePortal() { return false; }
+  virtual void stopCaptivePortal() {}
+  virtual void scan() = 0;
+  virtual bool scanning() const = 0;
+  virtual int scanCount() const = 0;
+  virtual WifiNetwork networkAt(int index) const = 0;
+  virtual std::vector<WifiNetwork> scanResults() const = 0;
+  virtual void setWebState(bool connected, const char *ssid, const char *ip,
+                           int rssi);
+  virtual void setWebScanCount(int count);
+  virtual void setWebScanEntry(int index, const char *ssid, int rssi,
+                               bool secured);
 };
 
 class WifiAdapter {
 public:
-	static void setDriver(WifiDriver *driver);
-	static WifiDriver *driver();
+  static void setDriver(WifiDriver *driver);
+  static WifiDriver *driver();
 
-	bool init() const;
-	bool enabled() const;
-	void setEnabled(bool enabled) const;
-	bool connected() const;
-	int rssi() const;
-	std::string ssid() const;
-	std::string ip() const;
-	std::string mac() const;
-	void configure(const std::string &ssid, const std::string &password) const;
-	void scan() const;
-	bool scanning() const;
-	int scanCount() const;
-	WifiNetwork networkAt(int index) const;
-	std::vector<WifiNetwork> scanResults() const;
-	void setWebState(bool connected, const char *ssid, const char *ip, int rssi) const;
-	void setWebScanCount(int count) const;
-	void setWebScanEntry(int index, const char *ssid, int rssi, bool secured) const;
+  bool init() const;
+  bool enabled() const;
+  void setEnabled(bool enabled) const;
+  bool connected() const;
+  int rssi() const;
+  std::string ssid() const;
+  std::string ip() const;
+  std::string mac() const;
+  void configure(const std::string &ssid, const std::string &password) const;
+  bool startAccessPoint(const std::string &ssid,
+                        const std::string &password) const;
+  void stopAccessPoint() const;
+  std::string accessPointMac() const;
+  bool startCaptivePortal() const;
+  void stopCaptivePortal() const;
+  void scan() const;
+  bool scanning() const;
+  int scanCount() const;
+  WifiNetwork networkAt(int index) const;
+  std::vector<WifiNetwork> scanResults() const;
+  void setWebState(bool connected, const char *ssid, const char *ip,
+                   int rssi) const;
+  void setWebScanCount(int count) const;
+  void setWebScanEntry(int index, const char *ssid, int rssi,
+                       bool secured) const;
 };
 
-inline WifiAdapter wifi()
-{
-	return WifiAdapter{};
-}
+inline WifiAdapter wifi() { return WifiAdapter{}; }
 
-}  // namespace gea::framework::network
+} // namespace gea::framework::network