No comment

Author: xaionaro@dx.center

Makefile

@@ -17,7 +17,7 @@ FIXTURE_MODULES := $(notdir $(wildcard tools/pkg/specgen/testdata/*/))
 NDK_SYSROOT := $(NDK_PATH)/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/include
 C2FFI_BIN   ?= c2ffi
 
-.PHONY: all capi specs idiomatic clean regen fixtures test lint check-examples e2e e2e-build e2e-examples
+.PHONY: all capi specs idiomatic clean regen fixtures test lint check-examples e2e e2e-build e2e-examples e2e-audio
 
 all: specs capi idiomatic
 
@@ -108,6 +108,10 @@ e2e: e2e-build
 e2e-examples:
 	./tests/e2e/run-examples.sh
 
+# Run audio recording E2E test (requires running emulator with audio + NDK)
+e2e-audio:
+	./tests/e2e/run-audio-e2e.sh
+
 clean:
 	@for m in $(MODULES); do rm -rf "capi/$$m/"; done
 	rm -rf spec/generated/

README.md

@@ -7,6 +7,11 @@
 
 Idiomatic Go bindings for the Android NDK, auto-generated from C headers to ensure full coverage and easy maintenance.
 
+## Requirements
+
+- **Android NDK r28** (28.0.13004108) or later
+- **API level 35** (Android 15) target
+
 ## Usage Examples
 
 ### Audio Playback (AAudio)
@@ -602,3 +607,30 @@ bindings, proper resource lifecycle (Close), error handling, and callback
 bridging. Writing CGo from scratch duplicates this work and lacks the
 automated test coverage this project maintains.
 -->
+
+## FAQ
+
+**Q: Why NativeActivity instead of GameActivity?**
+
+This project wraps NDK C headers via a three-stage generation pipeline. GameActivity is a Jetpack Java library (AAR in the AGDK), not an NDK C API. NativeActivity is the only activity model exposed by NDK headers themselves. GameActivity requires bundling a Java AAR + JNI bridging — fundamentally different from the C→Go pipeline. rust-mobile/ndk faces the identical constraint and also centers NativeActivity. A companion `gameactivity/` package is planned for wrapping the AGDK GameActivity C library.
+
+**Q: What about permissions, text input, and other Java-only APIs?**
+
+Android runtime permissions are Activity-driven Java APIs; the NDK `APermissionManager_checkPermission` only checks, it cannot request. The `jni/` package provides `HasPermission()` and `RequestPermission()` via JNI as the escape hatch. `examples/camera/display/` demonstrates the full permission request flow. This is inherent to Android's platform design — all native-first frameworks (Rust ndk, C++ NativeActivity) hit the same boundary. See [Platform Integration Guide](docs/platform-integration.md) for details.
+
+**Q: Why do examples use `unsafe.Pointer` and `runtime.LockOSThread()`?**
+
+`unsafe.Pointer` in audio I/O provides zero-copy buffer access — adding a copying wrapper would be a performance regression for the primary use case. `runtime.LockOSThread()` is the standard Go pattern for thread-affine APIs (EGL contexts, ALooper, AInputQueue) — it is not a leaky abstraction, it is how Go correctly interoperates with thread-local native APIs. The idiomatic layer hides `unsafe.Pointer` for all handle types behind typed Go structs with constructors and `Close()` methods. See [Thread Safety Guide](docs/thread-safety.md).
+
+**Q: Why `make` targets instead of Android Studio / Gradle?**
+
+There is no Go↔Gradle integration in the wider Go ecosystem; gomobile also uses a custom build tool. The provided Makefile produces complete, signed APKs ready for deployment. A standalone `go-ndk-build` CLI tool is planned to streamline APK packaging.
+
+**Q: Is the API stable?**
+
+The project is pre-release (v0.x). APIs may change as the overlay system evolves. Generated APIs track NDK header changes — running the pipeline with a new NDK version may change signatures. Semantic versioning will be adopted once the overlay format stabilizes.
+
+## Guides
+
+- [Thread Safety](docs/thread-safety.md) — when and why to use `runtime.LockOSThread()`
+- [Platform Integration](docs/platform-integration.md) — bridging to Java APIs via JNI

android/app.go

@@ -0,0 +1,64 @@
+//go:build android
+
+package android
+
+import (
+	"sync"
+	"unsafe"
+
+	"github.com/xaionaro-go/ndk/activity"
+	"github.com/xaionaro-go/ndk/window"
+)
+
+// App provides a high-level interface to an Android NativeActivity.
+type App struct {
+	mu        sync.Mutex
+	activity  *activity.Activity
+	window    *window.Window
+	windowPtr unsafe.Pointer
+}
+
+// Activity returns the underlying Activity.
+func (app *App) Activity() *activity.Activity {
+	app.mu.Lock()
+	defer app.mu.Unlock()
+	return app.activity
+}
+
+// Window returns the current native window, or nil if no window is available.
+func (app *App) Window() *window.Window {
+	app.mu.Lock()
+	defer app.mu.Unlock()
+	return app.window
+}
+
+// WindowSize returns the current window dimensions.
+// Returns (0, 0) if no window is available.
+func (app *App) WindowSize() (width, height int32) {
+	app.mu.Lock()
+	w := app.window
+	app.mu.Unlock()
+
+	if w == nil {
+		return 0, 0
+	}
+	return w.Width(), w.Height()
+}
+
+func (app *App) setActivity(act *activity.Activity) {
+	app.mu.Lock()
+	defer app.mu.Unlock()
+	app.activity = act
+}
+
+func (app *App) setWindow(ptr unsafe.Pointer) {
+	app.mu.Lock()
+	defer app.mu.Unlock()
+	if ptr == nil {
+		app.window = nil
+		app.windowPtr = nil
+	} else {
+		app.windowPtr = ptr
+		app.window = window.NewWindowFromPointer(ptr)
+	}
+}

android/doc.go

@@ -0,0 +1,8 @@
+//go:build android
+
+// Package android provides a high-level API for Android NativeActivity apps.
+//
+// It combines the lower-level NDK packages (activity, window, input) with
+// JNI helpers (jni) into an ergonomic interface for common platform tasks
+// like permission management, lifecycle handling, and UI operations.
+package android

android/lifecycle.go

@@ -0,0 +1,104 @@
+//go:build android
+
+package android
+
+import (
+	"unsafe"
+
+	"github.com/xaionaro-go/ndk/activity"
+	"github.com/xaionaro-go/ndk/input"
+)
+
+// Handlers defines callbacks for Android lifecycle events and input.
+// All callbacks receive the App instance for accessing platform APIs.
+type Handlers struct {
+	OnCreate             func(app *App)
+	OnResume             func(app *App)
+	OnPause              func(app *App)
+	OnDestroy            func(app *App)
+	OnWindowCreated      func(app *App)
+	OnWindowDestroyed    func(app *App)
+	OnWindowFocusChanged func(app *App, hasFocus bool)
+	OnInputEvent         func(app *App, event *input.Event) bool
+}
+
+// Run sets up NativeActivity lifecycle callbacks and manages the App instance.
+// Call this from an init() function in your main package.
+func Run(handlers Handlers) {
+	app := &App{}
+
+	activity.SetLifecycleCallbacks(activity.LifecycleCallbacks{
+		OnCreate: func(act *activity.Activity) {
+			app.setActivity(act)
+			if handlers.OnCreate != nil {
+				handlers.OnCreate(app)
+			}
+		},
+		OnNativeWindowCreated: func(act *activity.Activity, win unsafe.Pointer) {
+			app.setActivity(act)
+			app.setWindow(win)
+			if handlers.OnWindowCreated != nil {
+				handlers.OnWindowCreated(app)
+			}
+		},
+		OnResume: func(act *activity.Activity) {
+			app.setActivity(act)
+			if handlers.OnResume != nil {
+				handlers.OnResume(app)
+			}
+		},
+		OnPause: func(act *activity.Activity) {
+			if handlers.OnPause != nil {
+				handlers.OnPause(app)
+			}
+		},
+		OnWindowFocusChanged: func(_ *activity.Activity, hasFocus int32) {
+			if handlers.OnWindowFocusChanged != nil {
+				handlers.OnWindowFocusChanged(app, hasFocus != 0)
+			}
+		},
+		OnNativeWindowDestroyed: func(_ *activity.Activity, _ unsafe.Pointer) {
+			if handlers.OnWindowDestroyed != nil {
+				handlers.OnWindowDestroyed(app)
+			}
+			app.setWindow(nil)
+		},
+		OnInputQueueCreated: func(_ *activity.Activity, queuePtr unsafe.Pointer) {
+			if handlers.OnInputEvent != nil {
+				q := input.NewQueueFromPointer(queuePtr)
+				go drainInput(app, q, handlers.OnInputEvent)
+			}
+		},
+		OnDestroy: func(_ *activity.Activity) {
+			if handlers.OnDestroy != nil {
+				handlers.OnDestroy(app)
+			}
+			app.setActivity(nil)
+			app.setWindow(nil)
+		},
+	})
+}
+
+func drainInput(
+	app *App,
+	q *input.Queue,
+	handler func(app *App, event *input.Event) bool,
+) {
+	for {
+		ev := q.GetEvent()
+		if ev == nil {
+			return
+		}
+
+		if q.PreDispatchEvent(ev) {
+			continue
+		}
+
+		handled := handler(app, ev)
+		var result int32
+		if handled {
+			result = 1
+		}
+		q.FinishEvent(ev, result)
+	}
+}

android/permissions.go

@@ -0,0 +1,32 @@
+//go:build android
+
+package android
+
+import (
+	"github.com/xaionaro-go/ndk/jni"
+)
+
+// HasPermission checks if a runtime permission is currently granted.
+func (app *App) HasPermission(permission string) bool {
+	app.mu.Lock()
+	act := app.activity
+	app.mu.Unlock()
+
+	if act == nil {
+		return false
+	}
+	return jni.HasPermission(act.Pointer(), permission)
+}
+
+// RequestPermission shows the system permission dialog for the given permission.
+// This is asynchronous; use HasPermission to check the result after the user responds.
+func (app *App) RequestPermission(permission string) {
+	app.mu.Lock()
+	act := app.activity
+	app.mu.Unlock()
+
+	if act == nil {
+		return
+	}
+	jni.RequestPermission(act.Pointer(), permission)
+}

android/ui.go

@@ -0,0 +1,32 @@
+//go:build android
+
+package android
+
+import (
+	"github.com/xaionaro-go/ndk/jni"
+)
+
+// ShowToast displays an Android Toast message.
+func (app *App) ShowToast(message string) {
+	app.mu.Lock()
+	act := app.activity
+	app.mu.Unlock()
+
+	if act == nil {
+		return
+	}
+	jni.ShowToast(act.Pointer(), message)
+}
+
+// FillWindowColor fills the current window with a solid RGBA color.
+// Does nothing if no window is available.
+func (app *App) FillWindowColor(color uint32) {
+	app.mu.Lock()
+	wPtr := app.windowPtr
+	app.mu.Unlock()
+
+	if wPtr == nil {
+		return
+	}
+	jni.FillWindowColor(wPtr, color)
+}