Android Go NDK

https://github.com/androidgolab/ndk
Admin
Idiomatic Go bindings for the Android NDK with auto-generated coverage of 34 modules including...
Tokens:40,270
Snippets:319
Trust Score:7.5
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Quick start examples for ndkcli

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Basic commands to get started with ndkcli, including listing cameras, recording audio, checking thermal status, querying GPU, and reading sensor data.

```bash
# List cameras
adb shell /data/local/tmp/ndkcli camera list-details

# Record 5 seconds of audio
adb shell /data/local/tmp/ndkcli audio record --output /data/local/tmp/rec.pcm --duration 5s

# Check thermal status
adb shell /data/local/tmp/ndkcli thermal manager current-status

# Query GPU
adb shell /data/local/tmp/ndkcli gles2 info

# List sensors
adb shell /data/local/tmp/ndkcli sensor read --type 1
```

--------------------------------

### Event Loop (ALooper)

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Demonstrates setting up and interacting with the Android looper. This example shows how to prepare a looper, acquire it, and wake it up.

```go
package main

import (
	"log"
	"runtime"
	"time"
	"unsafe"

	"github.com/AndroidGoLab/ndk/looper"
)

func main() {
	runtime.LockOSThread()
	defer runtime.UnlockOSThread()


lp := looper.Prepare(int32(looper.ALOOPER_PREPARE_ALLOW_NON_CALLBACKS))
	defer func() {
		_ = lp.Close()
	}()


lp.Acquire()
go func() {
	time.Sleep(100 * time.Millisecond)

lp.Wake()
}()

	var fd, events int32
	var data unsafe.Pointer
	result := looper.LOOPER_POLL(looper.PollOnce(-1, &fd, &events, &data))

	switch result {
	case looper.ALOOPER_POLL_WAKE:
		log.Println("woke up")
	case looper.ALOOPER_POLL_TIMEOUT:
		log.Println("timed out")
	}
}
```

--------------------------------

### Initialize H.264 Decoder and Format

Source: https://context7.com/androidgolab/ndk/llms.txt

Demonstrates creating an H.264 decoder and configuring a media format. The actual codec configuration and start are commented out as they require an Activity context.

```go
package main

import (
    "fmt"
    "log"
    "unsafe"

    "github.com/AndroidGoLab/ndk/media"
)

func main() {
    // Create H.264 decoder
    codec := media.NewDecoder("video/avc")
    if codec == nil {
        log.Fatal("H.264 decoder not available")
    }
    defer codec.Close()

    // Create and populate format
    format := media.NewFormat()
    defer format.Close()

    format.
        SetString("mime", "video/avc").
        SetInt32("width", 1920).
        SetInt32("height", 1080)

    var w, h int32
    format.GetInt32("width", &w)
    format.GetInt32("height", &h)
    fmt.Printf("format: %s\n", format.ToString())
    fmt.Printf("dimensions: %dx%d\n", w, h)

    // Configure requires an Activity context; shown for reference:
    //   if err := codec.Configure(format, nil, nil, 0); err != nil {
    //       log.Fatalf("configure: %v", err)
    //   }
    //   if err := codec.Start(); err != nil {
    //       log.Fatalf("start: %v", err)
    //   }

    // Buffer processing loop pattern:
    const timeoutUs int64 = 10_000

    //   for {
    //       idx := codec.DequeueInputBuffer(timeoutUs)
    //       if idx < 0 { continue }
    //
    //       var bufSize uint64
    //       buf := codec.GetInputBuffer(uint64(idx), &bufSize)
    //       data := unsafe.Slice(buf, bufSize)
    //       n := copy(data, nalUnit)
    //
    //       codec.QueueInputBuffer(uint64(idx), 0, uint64(n), presentationUs, 0)
    //       // End of stream: pass uint32(media.AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM)
    //
    //       var info media.BufferInfo
    //       outIdx := codec.DequeueOutputBuffer(&info, timeoutUs)
    //       if outIdx == int64(media.AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED) { continue }
    //       if outIdx < 0 { continue }
    //
    //       var outSize uint64
    //       outBuf := codec.GetOutputBuffer(uint64(outIdx), &outSize)
    //       frame := unsafe.Slice(outBuf, outSize)
    //       processFrame(frame)
    //       codec.ReleaseOutputBuffer(uint64(outIdx), false)
    //   }

    _ = unsafe.Pointer(nil) // demonstrates package import
    _ = timeoutUs

    // Create H.264 encoder
    enc := media.NewEncoder("video/avc")
    if enc == nil {
        log.Fatal("H.264 encoder not available")
    }
    defer enc.Close()

    encFmt := media.NewFormat()
    defer encFmt.Close()

    encFmt.
        SetString("mime", "video/avc").
        SetInt32("width", 1920).
        SetInt32("height", 1080).
        SetInt32("bitrate", 4_000_000).
        SetInt32("frame-rate", 30).
        SetInt32("i-frame-interval", 1).
        SetInt32("color-format", 21).        // COLOR_FormatYUV420SemiPlanar
        SetInt32("bitrate-mode", int32(media.ABITRATE_MODE_CBR))

    // Configure as encoder: flags=1 (AMEDIACODEC_CONFIGURE_FLAG_ENCODE)
    //   const flagEncode uint32 = 1
    //   codec.Configure(encFmt, nil, nil, flagEncode)
    //   codec.Start()

    fmt.Println("codec setup complete")
}
```

--------------------------------

### Install ndkcli via pre-built binary

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Download the pre-built binary for your device architecture and push it to the device. Ensure the binary has execute permissions.

```bash
# Download for your device architecture
wget https://github.com/AndroidGoLab/ndk/releases/latest/download/ndkcli-android-arm64
adb push ndkcli-android-arm64 /data/local/tmp/ndkcli
adb shell chmod 755 /data/local/tmp/ndkcli
```

--------------------------------

### Java Usage Example for Sensor Bridge

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Illustrates how to use the Go-generated `Bridge` class in Java code. It shows obtaining a native sensor manager pointer via JNI and then using the bridge to get sensor information.

```Java
long ptr = nativeGetSensorManager(); // from JNI
Bridge bridge = Sensorbridge.newBridge(ptr);
String name = bridge.accelerometerName();
```

--------------------------------

### Complete Camera Capture Pipeline in Go

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Demonstrates the full lifecycle of setting up a camera capture session, from manager creation to starting and stopping repeating captures. Ensure proper cleanup order via defers.

```go
import "github.com/AndroidGoLab/ndk/camera"

// 1. Create manager
mgr := camera.NewManager()
deferr mgr.Close()

// 2. Discover cameras
ids, err := mgr.CameraIDList()
if err != nil {
    log.Fatal(err)
}

// 3. Read characteristics
chars, err := mgr.GetCameraCharacteristics(ids[0])
if err != nil {
    log.Fatal(err)
}
deferr chars.Close()

// Query sensor orientation
if chars.I32Count(uint32(camera.SensorOrientation)) > 0 {
    orient := chars.I32At(uint32(camera.SensorOrientation), 0)
    log.Printf("orientation: %d degrees", orient)
}

// Query stream configurations (format, width, height, isInput tuples)
scTag := uint32(camera.ScalerAvailableStreamConfigurations)
count := chars.I32Count(scTag)
for i := int32(0); i+3 < count; i += 4 {
    format := chars.I32At(scTag, i)
    w := chars.I32At(scTag, i+1)
    h := chars.I32At(scTag, i+2)
    isInput := chars.I32At(scTag, i+3)
    if isInput == 0 {
        log.Printf("output: format=%d %dx%d", format, w, h)
    }
}

// 4. Open camera with state callbacks
dev, err := mgr.OpenCamera(ids[0], camera.DeviceStateCallbacks{
    OnDisconnected: func() { log.Println("disconnected") },
    OnError:        func(code int) { log.Printf("error %d", code) },
})
if err != nil {
    log.Fatal(err)
}
deferr dev.Close()

// 5. Create capture request
req, err := dev.CreateCaptureRequest(camera.Preview)
if err != nil {
    log.Fatal(err)
}
deferr req.Close()

// 6. Create output target from ANativeWindow (from Surface/SurfaceTexture)
outTarget, err := camera.NewOutputTarget(nativeWindow)
if err != nil {
    log.Fatal(err)
}
deferr outTarget.Close()
req.AddTarget(outTarget)

// 7. Create session output container
sessOut, err := camera.NewSessionOutput(nativeWindow)
if err != nil {
    log.Fatal(err)
}
deferr sessOut.Close()

container, err := camera.NewSessionOutputContainer()
if err != nil {
    log.Fatal(err)
}
deferr container.Close()
container.Add(sessOut)

// 8. Create capture session with readiness gate
var wg sync.WaitGroup
wg.Add(1)
var readyOnce sync.Once

session, err := dev.CreateCaptureSession(container,
    camera.SessionStateCallbacks{
        OnReady:  func() { readyOnce.Do(wg.Done) },
        OnActive: func() { log.Println("session active") },
        OnClosed: func() { log.Println("session closed") },
    },
)
if err != nil {
    log.Fatal(err)
}
deferr session.Close()

wg.Wait()

// 9. Start repeating capture
session.SetRepeatingRequest(req)
// ... render frames ...
session.StopRepeating()

// Cleanup order (via defers): session -> container -> sessOut -> outTarget -> req -> dev -> mgr
```

--------------------------------

### Example Manifest for Specgen

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Defines package name and include paths for the spec generation stage.

```yaml
GENERATOR:
  PackageName: looper
  Includes: ["android/looper.h"]
  FlagGroups:
    - { name: LDFLAGS, flags: [-landroid] }
```

--------------------------------

### Native Handle Interoperability Example

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Demonstrates obtaining and reconstructing native handles using `UintPtr` and `Pointer`. Use for passing handles between Go and other systems.

```go
mgr := camera.NewManager()
ptr := mgr.UintPtr()                         // Get as uintptr
mgr2 := camera.NewManagerFromUintPtr(ptr)     // Reconstruct
mgr3 := camera.NewManagerFromPointer(rawPtr)  // From unsafe.Pointer
```

--------------------------------

### Audio Playback and Recording with Go

Source: https://context7.com/androidgolab/ndk/llms.txt

Demonstrates audio playback and recording using the `audio` module. Configure stream properties like sample rate, channel count, and format before opening and starting the stream. Handles playback by writing to the stream and recording by reading from it.

```go
package main

import (
    "log"
    "time"
    "unsafe"

    "github.com/AndroidGoLab/ndk/audio"
)

func main() {
    // --- Playback ---
    builder, err := audio.NewStreamBuilder()
    if err != nil {
        log.Fatalf("create stream builder: %v", err)
    }
    defer builder.Close()

    builder.
        SetDirection(audio.Output).
        SetSampleRate(44100).
        SetChannelCount(2).
        SetFormat(audio.PcmFloat).
        SetPerformanceMode(audio.LowLatency).
        SetSharingMode(audio.Shared)

    stream, err := builder.Open()
    if err != nil {
        log.Fatalf("open stream: %v", err)
    }
    defer stream.Close()

    log.Printf("stream: %d Hz, %d ch, state=%s, burst=%d frames",
        stream.SampleRate(), stream.ChannelCount(),
        stream.State(), stream.FramesPerBurst())

    if err := stream.Start(); err != nil {
        log.Fatalf("start: %v", err)
    }

    framesPerBurst := stream.FramesPerBurst()
    buf := make([]float32, int(framesPerBurst)*2)
    bufBytes := unsafe.Slice((*byte)(unsafe.Pointer(&buf[0])),
        len(buf)*int(unsafe.Sizeof(buf[0])))

    totalFrames := int32(44100 * 2) // 2 seconds of silence
    written := int32(0)
    for written < totalFrames {
        framesToWrite := framesPerBurst
        if remaining := totalFrames - written; remaining < framesToWrite {
            framesToWrite = remaining
        }
        n, err := stream.Write(bufBytes, framesToWrite, time.Second)
        if err != nil {
            log.Fatalf("write: %v", err)
        }
        written += n
    }
    log.Printf("wrote %d frames, xruns: %d", written, stream.XRunCount())
    stream.Stop()

    // --- Recording ---
    recBuilder, _ := audio.NewStreamBuilder()
    defer recBuilder.Close()

    recBuilder.
        SetDirection(audio.Input).
        SetSampleRate(48000).
        SetChannelCount(1).
        SetFormat(audio.PcmI16).
        SetPerformanceMode(audio.LowLatency).
        SetSharingMode(audio.Shared)

    recStream, _ := recBuilder.Open()
    defer recStream.Close()
    recStream.Start()

    recBuf := make([]int16, 1024)
    recBufBytes := unsafe.Slice((*byte)(unsafe.Pointer(&recBuf[0])),
        len(recBuf)*int(unsafe.Sizeof(recBuf[0])))
    totalRecFrames := recStream.SampleRate() // 1 second
    var captured []int16
    for int32(len(captured)) < totalRecFrames {
        n, err := recStream.Read(recBufBytes, int32(len(recBuf)), time.Second)
        if err != nil {
            log.Fatalf("read: %v", err)
        }
        captured = append(captured, recBuf[:n]...)
    }
    recStream.Stop()
    log.Printf("captured %d frames", len(captured))
}

```

--------------------------------

### H.264 Decoder Setup in Go

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Use this to create and configure an H.264 decoder. Requires specifying the MIME type and optionally setting video dimensions. Ensure the decoder is available on the device.

```go
import "github.com/AndroidGoLab/ndk/media"

// Create H.264 decoder (wraps AMediaCodec_createDecoderByType)
codec := media.NewDecoder("video/avc")
if codec == nil {
    log.Fatal("H.264 decoder not available")
}
defer codec.Close()

// Configure format (wraps AMediaFormat)
format := media.NewFormat()
defere.Close()

format.
    SetString("mime", "video/avc").
    SetInt32("width", 1920).
    SetInt32("height", 1080)

// Verify properties
var width int32
format.GetInt32("width", &width)  // returns bool

// Configure as decoder: flags=0 (requires Activity context)
codec.Configure(format, nil, nil, 0)
codec.Start()
```

--------------------------------

### Install ndkcli by building from source

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Build the ndkcli tool from source using 'make'. This requires the Android NDK to be set up. Push the built binary to the device and ensure it has execute permissions.

```bash
make ndkcli                                # → build/ndkcli (arm64)
adb push build/ndkcli /data/local/tmp/
adb shell chmod 755 /data/local/tmp/ndkcli
```

--------------------------------

### H.264 Encoder Setup in Go

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Use this to create and configure an H.264 encoder. Requires specifying MIME type, dimensions, bitrate, and frame rate. Optional parameters include bitrate mode, profile, and level.

```go
import "github.com/AndroidGoLab/ndk/media"

// Create H.264 encoder (wraps AMediaCodec_createEncoderByType)
codec := media.NewEncoder("video/avc")
if codec == nil {
    log.Fatal("H.264 encoder not available")
}
defer codec.Close()

// Configure encoder format with required parameters.
// Format keys are plain strings matching the NDK AMEDIAFORMAT_KEY_* constants.
format := media.NewFormat()
defere.Close()

format.
    SetString("mime", "video/avc").       // AMEDIAFORMAT_KEY_MIME
    SetInt32("width", 1920).              // AMEDIAFORMAT_KEY_WIDTH
    SetInt32("height", 1080).             // AMEDIAFORMAT_KEY_HEIGHT
    SetInt32("bitrate", 4_000_000).       // AMEDIAFORMAT_KEY_BIT_RATE (bits/sec)
    SetInt32("frame-rate", 30).           // AMEDIAFORMAT_KEY_FRAME_RATE
    SetInt32("i-frame-interval", 1).      // AMEDIAFORMAT_KEY_I_FRAME_INTERVAL (seconds)
    SetInt32("color-format", 21)          // COLOR_FormatYUV420SemiPlanar (0x15)

// Optional: set bitrate mode (CBR for streaming, VBR for quality)
// media.ABITRATE_MODE_CBR = 2, media.ABITRATE_MODE_VBR = 1
format.SetInt32("bitrate-mode", int32(media.ABITRATE_MODE_CBR))

// Optional: set H.264 profile and level
format.SetInt32("profile", 8)   // AVCProfileHigh
format.SetInt32("level", 512)  // AVCLevel31

// Configure as encoder: flags=1 (AMEDIACODEC_CONFIGURE_FLAG_ENCODE)
// surface=nil for buffer-mode input, crypto=nil for no DRM
const configureFlagEncode uint32 = 1  // media.AMEDIACODEC_CONFIGURE_FLAG_ENCODE
codec.Configure(format, nil, nil, configureFlagEncode)
codec.Start()
```

--------------------------------

### Run E2E Examples Test

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Execute end-to-end tests for ndkcli commands on a connected device or emulator. Requires a connected device or emulator.

```bash
make e2e-examples-test
```

--------------------------------

### EGL Context and OpenGL ES Setup

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Configures an EGL display, chooses a configuration, creates a surface and context, and makes it current for OpenGL ES operations. Requires locking the OS thread.

```go
import (
    "runtime"
    "github.com/AndroidGoLab/ndk/egl"
    "github.com/AndroidGoLab/ndk/gles2"
)

runtime.LockOSThread()
deffer runtime.UnlockOSThread()

display := egl.GetDisplay(egl.DefaultDisplay)
eg.Initialize(display, nil, nil)

config := egl.ChooseConfig(display, attribs)
surface := egl.CreateWindowSurface(display, config, nativeWindow, nil)
context := egl.CreateContext(display, config, egl.NoContext, contextAttribs)

eg.MakeCurrent(display, surface, surface, context)
deffer eg.MakeCurrent(display, egl.NoSurface, egl.NoSurface, egl.NoContext)
deffer eg.DestroyContext(display, context)
deffer eg.DestroySurface(display, surface)
deffer eg.Terminate(display)

// Now use OpenGL ES on this thread
gles2.ClearColor(0.2, 0.3, 0.3, 1.0)
gles2.Clear(gles2.ColorBufferBit)
eg.SwapBuffers(display, surface)
```

--------------------------------

### Looper Overlay Configuration

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Example YAML overlay file for the 'looper' module. Defines Go mappings for C types and functions, including renaming, destructors, and method generation.

```yaml
module: looper
package:
  go_name: looper
  go_import: github.com/AndroidGoLab/ndk/looper
  doc: "Package looper provides Go bindings for Android ALooper."
types:
  ALooper:
    go_name: Looper # ALooper -> Looper
    destructor: ALooper_release # generates Close() method
    pattern: ref_counted
  Looper_event_t:
    go_name: Event
    strip_prefix: ALOOPER_ # ALOOPER_EVENT_INPUT -> EventInput
functions:
  ALooper_prepare:
    go_name: Prepare
    returns_new: Looper # returns *Looper, acts as constructor
  ALooper_wake:
    receiver: Looper # becomes method: (*Looper).Wake()
    go_name: Wake
  ALooper_release:
    skip: true # handled by destructor, don't expose

```

--------------------------------

### Query and Read Android Sensors

Source: https://context7.com/androidgolab/ndk/llms.txt

Demonstrates how to get a sensor manager instance, query individual sensor properties like name, vendor, resolution, and minimum delay. It also shows how to set up continuous event reading using the looper package for a specific sensor.

```go
package main

import (
    "fmt"
    "log"
    "runtime"

    "github.com/AndroidGoLab/ndk/looper"
    "github.com/AndroidGoLab/ndk/sensor"
)

// probeSensor safely checks whether a sensor is present (NULL pointer panics on Name()).
func probeSensor(mgr *sensor.Manager, t sensor.Type) (name, vendor string, ok bool) {
    defer func() {
        if r := recover(); r != nil {
            ok = false
        }
    }()
    s := mgr.DefaultSensor(t)
    name = s.Name()
    vendor = s.Vendor()
    return name, vendor, name != ""
}

func main() {
    mgr := sensor.GetInstance()

    accel := mgr.DefaultSensor(sensor.Accelerometer)
    fmt.Printf("Accelerometer: %s (%s)\n", accel.Name(), accel.Vendor())
    fmt.Printf("  Resolution: %g, MinDelay: %d µs\n",
        accel.Resolution(), accel.MinDelay())
    fmt.Printf("  WakeUp: %v\n", accel.IsWakeUpSensor())

    types := []sensor.Type{
        sensor.Gyroscope, sensor.Light, sensor.Proximity,
        sensor.MagneticField, sensor.Pressure, sensor.HeartRate,
        sensor.HingeAngle, sensor.StepCounter,
    }
    for _, t := range types {
        if name, vendor, ok := probeSensor(mgr, t); ok {
            fmt.Printf("[+] %d: %s (%s)\n", t, name, vendor)
        } else {
            fmt.Printf("[-] %d: not available\n", t)
        }
    }

    // Continuous event reading (ALooper-based, must run on Android):
    runtime.LockOSThread()
    defer runtime.UnlockOSThread()

    lp := looper.Prepare(int32(looper.ALOOPER_PREPARE_ALLOW_NON_CALLBACKS))
    defer lp.Close()

    const sensorIdent = 1
    queue := mgr.CreateEventQueue(lp.Pointer(), sensorIdent, nil, nil)
    defer mgr.DestroyEventQueue(queue)

    queue.EnableSensor(accel)
    queue.SetEventRate(accel, 100_000) // 100 ms between events
    defer queue.DisableSensor(accel)

    for i := 0; i < 5; i++ {
        ident := looper.LOOPER_POLL(looper.PollOnce(-1, nil, nil, nil))
        if ident == looper.LOOPER_POLL(sensorIdent) {
            for queue.HasEvents() > 0 {
                log.Println("sensor event received")
            }
        }
    }
}
```

--------------------------------

### Initialize Camera Manager and List Cameras

Source: https://context7.com/androidgolab/ndk/llms.txt

Demonstrates creating a camera manager, listing available camera IDs, and querying basic camera characteristics like sensor orientation and available stream configurations. Ensure the camera ID is valid before proceeding.

```go
package main

import (
    "fmt"
    "log"
    "sync"

    "github.com/AndroidGoLab/ndk/camera"
)

func main() {
    mgr := camera.NewManager()
    defer mgr.Close()

    ids, err := mgr.CameraIDList()
    if err != nil {
        log.Fatalf("list cameras: %v", err)
    }
    fmt.Printf("found %d cameras: %v\n", len(ids), ids)

    // Query characteristics
    chars, err := mgr.GetCameraCharacteristics(ids[0])
    if err != nil {
        log.Fatalf("characteristics: %v", err)
    }
    defer chars.Close()

    if chars.I32Count(uint32(camera.SensorOrientation)) > 0 {
        fmt.Printf("sensor orientation: %d°\n",
            chars.I32At(uint32(camera.SensorOrientation), 0))
    }

    // Count output stream configurations
    scTag := uint32(camera.ScalerAvailableStreamConfigurations)
    count := chars.I32Count(scTag)
    outputs := 0
    for i := int32(0); i+3 < count; i += 4 {
        if chars.I32At(scTag, i+3) == 0 { // isInput == 0
            outputs++
        }
    }
    fmt.Printf("%d output stream configurations\n", outputs)

    // Open camera with state callbacks
    dev, err := mgr.OpenCamera(ids[0], camera.DeviceStateCallbacks{
        OnDisconnected: func() { log.Println("camera disconnected") },
        OnError:        func(code int) { log.Printf("camera error %d", code) },
    })
    if err != nil {
        log.Fatalf("open camera: %v", err)
    }
    defer dev.Close()

    // Create a capture request (Preview template)
    req, err := dev.CreateCaptureRequest(camera.Preview)
    if err != nil {
        log.Fatalf("capture request: %v", err)
    }
    defer req.Close()

    // Full session pipeline (requires ANativeWindow from a Surface):
    //
    //   outTarget, _ := camera.NewOutputTarget(nativeWindow)
    //   defer outTarget.Close()
    //   req.AddTarget(outTarget)
    //
    //   sessOut, _ := camera.NewSessionOutput(nativeWindow)
    //   defer sessOut.Close()
    //   container, _ := camera.NewSessionOutputContainer()
    //   defer container.Close()
    //   container.Add(sessOut)
    //
    //   var wg sync.WaitGroup
    //   wg.Add(1)
    //   var once sync.Once
    //   session, _ := dev.CreateCaptureSession(container,
    //       camera.SessionStateCallbacks{
    //           OnReady:  func() { once.Do(wg.Done) },
    //           OnActive: func() { log.Println("active") },
    //           OnClosed: func() { log.Println("closed") },
    //       })
    //   defer session.Close()
    //   wg.Wait()
    //   session.SetRepeatingRequest(req)
    //   // ... render frames ...
    //   session.StopRepeating()

    _ = sync.WaitGroup{} // referenced above
    fmt.Printf("camera %s opened, request created\n", dev.GetID())
}

```

--------------------------------

### Check thermal status

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Get the current thermal status of the device or monitor it over a specified interval and duration.

```bash
# One-shot thermal status
adb shell /data/local/tmp/ndkcli thermal manager current-status

# Monitor thermal status every 2 seconds for 30 seconds
adb shell /data/local/tmp/ndkcli thermal monitor --interval 2s --duration 30s
```

--------------------------------

### Create and Configure System Settings

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Creates a configuration object to access system settings like screen density, orientation, size, and SDK version. Ensure to close the configuration object when done.

```go
import "github.com/AndroidGoLab/ndk/config"

cfg := config.NewConfig()
def cfg.Close()

log.Printf("density: %d", cfg.Density())
log.Printf("orientation: %d", cfg.Orientation())
log.Printf("screen size: %d", cfg.ScreenSize())
log.Printf("SDK version: %d", cfg.SdkVersion())
log.Printf("screen: %dx%d dp", cfg.ScreenWidthDp(), cfg.ScreenHeightDp())
```

--------------------------------

### Example Spec Output from Specgen

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Abridged structured YAML specification containing types, enums, and functions extracted from C headers.

```yaml
module: looper
source_package: github.com/AndroidGoLab/ndk/capi/looper
types:
  ALooper:
    kind: opaque_ptr
    c_type: ALooper
    go_type: "*C.ALooper"
enums:
  Looper_event_t:
    - { name: ALOOPER_EVENT_INPUT, value: 1 }
    - { name: ALOOPER_EVENT_OUTPUT, value: 2 }
functions:
  ALooper_prepare:
    c_name: ALooper_prepare
    params: [{ name: opts, type: int32 }]
    returns: "*ALooper"
```

--------------------------------

### Initialize EGL Display, Context, and Surface in Go

Source: https://context7.com/androidgolab/ndk/llms.txt

Demonstrates initializing an EGL display, choosing a configuration, creating an off-screen Pbuffer surface, and creating an OpenGL ES 2.0 context. All EGL calls must be made on the thread that holds the context. Use `CreateWindowSurface` for on-screen rendering and `SwapBuffers` for presenting frames.

```go
package main

import (
    "fmt"
    "log"
    "runtime"

    "github.com/AndroidGoLab/ndk/egl"
    "github.com/AndroidGoLab/ndk/gles2"
)

func main() {
    runtime.LockOSThread()
    defer runtime.UnlockOSThread()

    var defaultDisplay egl.EGLNativeDisplayType
    display := egl.GetDisplay(defaultDisplay)
    if display == nil {
        log.Fatal("GetDisplay failed")
    }

    var major, minor egl.Int
    if egl.Initialize(display, &major, &minor) == egl.False {
        log.Fatalf("Initialize failed: 0x%X", egl.GetError())
    }
    defer egl.Terminate(display)
    fmt.Printf("EGL %d.%d — vendor: %s\n", major, minor,
        egl.QueryString(display, egl.EGL_VENDOR))

    egl.BindAPI(egl.EGLenum(egl.OpenglEsApi))

    attribs := [...]egl.Int{
        egl.SurfaceType, egl.PbufferBit,
        egl.RenderableType, egl.OpenglEs2Bit,
        egl.RedSize, 8, egl.GreenSize, 8,
        egl.BlueSize, 8, egl.AlphaSize, 8,
        egl.None,
    }
    var config egl.EGLConfig
    var numConfigs egl.Int
    egl.ChooseConfig(display, &attribs[0], &config, 1, &numConfigs)
    fmt.Printf("found %d matching config(s)\n", numConfigs)

    pbufAttribs := [...]egl.Int{egl.Width, 64, egl.Height, 64, egl.None}
    surface := egl.CreatePbufferSurface(display, config, &pbufAttribs[0])
    defer egl.DestroySurface(display, surface)

    ctxAttribs := [...]egl.Int{egl.ContextClientVersion, 2, egl.None}
    ctx := egl.CreateContext(display, config, nil, &ctxAttribs[0])
    defer func() {
        egl.MakeCurrent(display, nil, nil, nil)
        egl.DestroyContext(display, ctx)
    }()

    egl.MakeCurrent(display, surface, surface, ctx)
    fmt.Println("context current — GL commands available")

    // Example GL usage
    vendor := gles2.GetString(gles2.GL_VENDOR)
    _ = vendor // *gles2.GLubyte — convert to string via unsafe if needed

    // For on-screen rendering, use CreateWindowSurface instead of pbuffer:
    //   win := window.NewWindowFromPointer(rawPtr)
    //   surface := egl.CreateWindowSurface(display, config,
    //       egl.EGLNativeWindowType(win.UintPtr()), nil)
    //   // per-frame:
    //   egl.SwapBuffers(display, surface)
}
```

--------------------------------

### Sensor Querying

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Retrieves information about the default accelerometer sensor. This example shows how to access sensor name, vendor, resolution, and minimum delay.

```go
package main

import (
	"fmt"

	"github.com/AndroidGoLab/ndk/sensor"
)

func main() {
	mgr := sensor.GetInstance()
	accel := mgr.DefaultSensor(sensor.Accelerometer)

	fmt.Printf("Sensor: %s (%s)\n", accel.Name(), accel.Vendor())
	fmt.Printf("Resolution: %g, min delay: %d µs\n",
		accel.Resolution(), accel.MinDelay())
}
```

--------------------------------

### Get Choreographer Instance

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Obtains the per-thread singleton Choreographer instance, which requires an active Looper on the calling thread. Used for VSync timing.

```go
import "github.com/AndroidGoLab/ndk/choreographer"

// Obtain the per-thread singleton (requires an active Looper on the thread)
ch := choreographer.GetInstance()
if ch == nil {
    log.Fatal("no choreographer — is a Looper prepared on this thread?")
}
// Frame callbacks are registered via the NDK's AChoreographer_postFrameCallback.
// Typical game loop: GetInstance -> register callback -> render -> re-register.
```

--------------------------------

### Show All Device Configuration

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Display all available configuration values for the device, including density, orientation, screen size, and SDK version.

```bash
adb shell /data/local/tmp/ndkcli config show
```

--------------------------------

### Go: Media Buffer Processing Loop

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Demonstrates the idiomatic buffer processing loop using the media package. Ensure correct handling of input and output buffer indices and flags.

```go
import (
    "unsafe"
    "github.com/AndroidGoLab/ndk/media"
)

for {
    // 1. Dequeue input buffer
    idx := codec.DequeueInputBuffer(timeoutUs)
    if idx < 0 { continue }  // no buffer available yet

    // 2. Fill with data (NAL units for video, PCM for audio)
    var bufSize uint64
    buf := codec.GetInputBuffer(uint64(idx), &bufSize)
    data := unsafe.Slice(buf, bufSize)
    n := copy(data, inputFrame)

    // 3. Queue for processing
    codec.QueueInputBuffer(uint64(idx), 0, uint64(n), presentationTimeUs, 0)
    // End of stream: pass uint32(media.AMEDIACODEC_BUFFER_FLAG_END_OF_STREAM)

    // 4. Dequeue output buffer with BufferInfo
    var info media.BufferInfo
    outIdx := codec.DequeueOutputBuffer(&info, timeoutUs)
    if outIdx == int64(media.AMEDIACODEC_INFO_OUTPUT_FORMAT_CHANGED) {
        continue  // output format changed, query new format
    }
    if outIdx < 0 { continue }

    // 5. Consume output — info.Offset, info.Size, info.PresentationTimeUs, info.Flags
    var outSize uint64
    outBuf := codec.GetOutputBuffer(uint64(outIdx), &outSize)
    outData := unsafe.Slice(outBuf, outSize)
    processOutput(outData)

    // 6. Release back to codec (render=true to send to surface)
    codec.ReleaseOutputBuffer(uint64(outIdx), false)
}
```

--------------------------------

### Check Sensor Availability in Go

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Safely checks if a sensor is available by attempting to get its name. It recovers from panics that occur when a sensor is absent.

```go
func probeSensor(mgr *sensor.Manager, t sensor.Type) (name string, ok bool) {
    defer func() {
        if r := recover(); r != nil {
            ok = false
        }
    }()
    s := mgr.DefaultSensor(t)
    name = s.Name()
    return name, name != ""
}
```

--------------------------------

### NDK Project Structure

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Overview of the NDK project's directory layout. This structure organizes build scripts, tools, generated code, and examples.

```plaintext
.
├── Makefile                      # Build orchestration
├── tools/
│   ├── cmd/
│   │   ├── specgen/              # Stage 1: spec extraction via c2ffi
│   │   ├── capigen/              # Stage 2: CGo wrapper generator
│   │   ├── idiomgen/             # Stage 3: idiomatic Go generator
│   │   ├── headerspec/           # Standalone header spec extraction tool
│   │   └── ndk-build/            # APK packaging tool
│   └── pkg/
│       ├── c2ffi/                # c2ffi invocation and JSON→spec conversion
│       ├── capigen/              # CGo code generation from spec + manifest
│       ├── headerspec/           # Header spec extraction logic
│       ├── specgen/              # Spec writing and legacy Go AST parsing
│       ├── specmodel/            # Spec data model (types, enums, functions)
│       ├── idiomgen/             # Merge, resolve, template rendering
│       └── overlaymodel/         # Overlay data model (annotations)
├── capi/
│   ├── manifests/                # capigen config per module (hand-written)
│   └── {module}/                 # Generated raw CGo packages
├── spec/
│   ├── generated/                # Generated YAML specs (intermediate)
│   └── overlays/                 # Hand-written semantic overlays
├── templates/                    # Go text templates for code generation
├── {module}/                     # Generated idiomatic Go packages (final output)
├── jni/                          # Hand-written JNI helpers (activity, permissions, etc.)
├── e2e/                          # End-to-end tests (Android emulator)
└── examples/                     # Usage examples per module

```

--------------------------------

### Query audio system capabilities

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Probe the audio system to get information about stream capabilities such as channel count, sample rate, and frames per burst.

```bash
# Open a probe stream and print audio properties
adb shell /data/local/tmp/ndkcli audio stream-builder new
adb shell /data/local/tmp/ndkcli audio stream channel-count
adb shell /data/local/tmp/ndkcli audio stream sample-rate
adb shell /data/local/tmp/ndkcli audio stream frames-per-burst
```

--------------------------------

### Add New Module - Step 4: Create Overlays

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Create the overlay file for a new module. This file annotates types with Go names, assigns functions as methods, and configures constructors/destructors.

```bash
4. Create `spec/overlays/{module}.yaml` -- annotate types with Go names, assign functions as methods, configure constructors/destructors, error types, etc.
```

--------------------------------

### Basic Event Loop with Looper

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Sets up a basic event loop using ALooper, demonstrating cross-goroutine wake-up and polling for events. Requires locking the OS thread.

```go
import (
    "runtime"
    "github.com/AndroidGoLab/ndk/looper"
)

runtime.LockOSThread()
deffer runtime.UnlockOSThread()

lp := looper.Prepare(int32(looper.ALOOPER_PREPARE_ALLOW_NON_CALLBACKS))
deffer lp.Close()

// Cross-goroutine wake
lp.Acquire()  // extra reference for other goroutine
go func() {
    time.Sleep(100 * time.Millisecond)
    lp.Wake()  // safe after Acquire
}()

// Poll
result := looper.PollOnce(-1, nil, nil, nil)
switch {
case result == int32(looper.ALOOPER_POLL_WAKE):
    log.Println("woken up")
case result == int32(looper.ALOOPER_POLL_TIMEOUT):
    log.Println("timed out")
case result >= 0:
    log.Printf("event from ident %d", result)
}
```

--------------------------------

### Decode Image File

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Decodes an image file (e.g., JPEG) from a POSIX file descriptor into a pixel buffer. This example uses lower-level C API wrappers for image decoding.

```go
package main

import (
	"fmt"
	"log"
	syscall "syscall"
	"unsafe"

	capidec "github.com/AndroidGoLab/ndk/capi/imagedecoder"
	"github.com/AndroidGoLab/ndk/image"
)

func main() {
	// 1. Open the image file via POSIX fd.
	fd, err := syscall.Open("/sdcard/photo.jpg", syscall.O_RDONLY, 0)
	if err != nil {
		log.Fatalf("open file: %v", err)
	}
	defer syscall.Close(fd)

	// 2. Create a Decoder from the fd.
	//    The factory function is not yet in the high-level image package,
	//    so we call the capi function and wrap the result.
	var decPtr *capidec.AImageDecoder
	if rc := capidec.AImageDecoder_createFromFd(int32(fd), &decPtr); rc != 0 {
		log.Fatalf("create decoder: error %d", rc)
	}
	decoder := image.NewDecoderFromPointer(unsafe.Pointer(decPtr))
	defer decoder.Close()

	// 3. Query image dimensions from the header.
	headerPtr := capidec.AImageDecoder_getHeaderInfo(decPtr)
	width := capidec.AImageDecoderHeaderInfo_getWidth(headerPtr)
	height := capidec.AImageDecoderHeaderInfo_getHeight(headerPtr)
	fmt.Printf("Image: %d x %d\n", width, height)

	// 4. Query the stride and allocate the pixel buffer.
	stride := decoder.MinimumStride()
	bufSize := stride * uint64(height)
	pixels := make([]byte, bufSize)
	fmt.Printf("Stride: %d bytes, buffer: %d bytes\n", stride, bufSize)

	// 5. Decode the image into the buffer.
	if err := decoder.Decode(unsafe.Pointer(&pixels[0]), stride, bufSize); err != nil {
		log.Fatalf("decode: %v", err)
	}

	fmt.Printf("Decoded %d bytes of RGBA pixel data.\n", bufSize)
}
```

--------------------------------

### Add New Module - Step 1: Create Manifest

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Create the manifest file for a new module. This file configures which NDK headers to parse and which symbols to accept.

```bash
1. Create `capi/manifests/{module}.yaml` -- configure which NDK headers to parse and which symbols to accept.
```

--------------------------------

### Defer-Based Resource Cleanup in Go

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Illustrates the recommended approach for managing NDK resource lifecycles using `defer`. Resources are closed in the reverse order of their creation, ensuring that dependencies are handled correctly and preventing resource leaks. This pattern is crucial for maintaining application stability.

```go
mgr := camera.NewManager()
deferr func() {
    if err := mgr.Close(); err != nil {
        log.Printf("manager close: %v", err)
    }
}()

dev, err := mgr.OpenCamera(camID, callbacks)
if err != nil {
    log.Fatal(err)
}
deferr dev.Close()

req, err := dev.CreateCaptureRequest(camera.Preview)
if err != nil {
    log.Fatal(err)
}
deferr req.Close()
// Cleanup order: req -> dev -> mgr (reverse creation order)
```

--------------------------------

### Go: Reading an Asset File

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Demonstrates reading the entire content of an asset file into a byte slice. Ensure the asset is opened with appropriate flags and closed using defer.

```go
a := mgr.Open("data/config.json", asset.Streaming)
def a.Close()

totalLen := a.Length64()
buf := make([]byte, totalLen)
er := a.Read(unsafe.Pointer(&buf[0]), uint64(totalLen))
```

--------------------------------

### ALooper Event Loop with Wake

Source: https://context7.com/androidgolab/ndk/llms.txt

Illustrates setting up an ALooper event loop that can be woken from another goroutine. It demonstrates acquiring an extra reference to the looper, waking it after a delay, and handling different poll results like WAKE, TIMEOUT, and ERROR.

```go
package main

import (
    "log"
    "runtime"
    "time"
    "unsafe"

    "github.com/AndroidGoLab/ndk/looper"
)

func main() {
    runtime.LockOSThread()
    defer runtime.UnlockOSThread()

    lp := looper.Prepare(int32(looper.ALOOPER_PREPARE_ALLOW_NON_CALLBACKS))
    if lp == nil {
        log.Fatal("failed to prepare looper")
    }
    defer lp.Close()

    // Acquire extra reference so Wake is safe from another goroutine.
    lp.Acquire()

    go func() {
        time.Sleep(100 * time.Millisecond)
        log.Println("goroutine: waking looper")
        lp.Wake()
    }()

    var fd, events int32
    var data unsafe.Pointer
    result := looper.LOOPER_POLL(looper.PollOnce(-1, &fd, &events, &data))

    switch result {
    case looper.ALOOPER_POLL_WAKE:
        log.Println("WAKE: looper woken successfully")
    case looper.ALOOPER_POLL_TIMEOUT:
        log.Println("TIMEOUT")
    case looper.ALOOPER_POLL_ERROR:
        log.Fatal("ERROR")
    default:
        log.Printf("fd event: fd=%d events=%d", result, events)
    }
}
```

--------------------------------

### IPC: Sharing Hardware Buffers via Unix Sockets

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Provides code examples for sending a hardware buffer handle from one process to another using Unix domain sockets. The sender uses `SendHandleToUnixSocket`, and the receiver uses `RecvHandleFromUnixSocket`.

```go
// Sender process:
buf.SendHandleToUnixSocket(socketFd)

// Receiver process:
received, err := hwbuf.RecvHandleFromUnixSocket(socketFd)
if err != nil {
    log.Fatalf("recv handle: %v", err)
}
defer received.Close()
```

--------------------------------

### Window Management

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Creates a window object from a raw pointer, manages its reference count, and allows setting geometry and frame rate. Use Acquire() and Close() for reference counting.

```go
import "github.com/AndroidGoLab/ndk/window"

win := window.NewWindowFromPointer(rawPtr)
// Reference counting
win.Acquire()  // increment ref count
deffer win.Close()  // decrement ref count (calls ANativeWindow_release)

w := win.Width()
h := win.Height()
fmt.Printf("%dx%d\n", w, h)

win.SetBuffersGeometry(1920, 1080, window.Rgba8888)
win.SetFrameRate(60.0, 0)
```

--------------------------------

### Add New Module - Step 3: Generate CGo Bindings

Source: https://github.com/androidgolab/ndk/blob/main/README.md

Run 'make capi' to generate the raw CGo binding package. This is the second stage of module generation.

```bash
3. Run `make capi` to generate the raw CGo binding package.
```

--------------------------------

### Go: Media Error Handling

Source: https://github.com/androidgolab/ndk/blob/main/llms.txt

Illustrates how to handle errors returned by media functions using `errors.Is`. Common configuration failures include unsupported formats or missing codecs.

```go
if err := codec.Configure(format, nil, nil, flags); err != nil {
    log.Fatalf("configure failed: %v", err)
    // Common causes: unsupported format, missing codec, wrong flags
}
```

```go
if err := codec.Start(); err != nil {
    log.Fatalf("start failed: %v", err)
}
```
Tokens:
Raw