refactor: extract camera capture logic into reusable library packages

Move gralloc allocation, IGBP stub, and camera connection/capture helpers
out of examples/camera_capture/main.go into library packages:

- camera/gralloc: gralloc buffer allocation via IAllocator HAL
- camera/igbp: IGraphicBufferProducer stub with gralloc buffers
- camera/: high-level Device API (Connect, ConfigureStream, CaptureFrame, Close)

The example shrinks from 917 to 81 lines. Both cmd/bindercli and
cmd/camera_fwk now import the shared libraries instead of duplicating
the raw transaction helpers and wire-format functions.

Author: xaionaro@dx.center

camera/device.go

@@ -0,0 +1,211 @@
+package camera
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	gfxCommon "github.com/xaionaro-go/binder/android/hardware/graphics/common"
+
+	fwkDevice "github.com/xaionaro-go/binder/android/frameworks/cameraservice/device"
+	fwkService "github.com/xaionaro-go/binder/android/frameworks/cameraservice/service"
+	"github.com/xaionaro-go/binder/binder"
+	cameraIGBP "github.com/xaionaro-go/binder/camera/igbp"
+	"github.com/xaionaro-go/binder/camera/gralloc"
+	"github.com/xaionaro-go/binder/servicemanager"
+)
+
+// Device represents a connected camera device with a configured capture
+// stream. Use Connect to create, ConfigureStream to set up the stream,
+// CaptureFrame to read frames, and Close to disconnect.
+type Device struct {
+	sm        *servicemanager.ServiceManager
+	transport binder.Transport
+
+	deviceUser fwkDevice.ICameraDeviceUser
+	callback   *deviceCallback
+
+	// Set after ConfigureStream.
+	igbpStub    *cameraIGBP.ProducerStub
+	grallocBufs [4]*gralloc.Buffer
+	streamID    int32
+	metadata    []byte
+	width       int32
+	height      int32
+}
+
+// Connect opens a connection to the camera device identified by cameraID
+// (typically "0" for the back camera).
+func Connect(
+	ctx context.Context,
+	sm *servicemanager.ServiceManager,
+	transport binder.Transport,
+	cameraID string,
+) (_ *Device, _err error) {
+	svc, err := sm.GetService(ctx, "android.frameworks.cameraservice.service.ICameraService/default")
+	if err != nil {
+		return nil, fmt.Errorf("getting camera service: %w", err)
+	}
+
+	proxy := fwkService.NewCameraServiceProxy(svc)
+	cb := &deviceCallback{}
+	stub := fwkDevice.NewCameraDeviceCallbackStub(cb)
+
+	stubBinder := stub.AsBinder().(*binder.StubBinder)
+	stubBinder.RegisterWithTransport(ctx, transport)
+	time.Sleep(100 * time.Millisecond)
+
+	deviceUser, err := proxy.ConnectDevice(ctx, stub, cameraID)
+	if err != nil {
+		return nil, fmt.Errorf("ConnectDevice: %w", err)
+	}
+
+	dev := &Device{
+		sm:         sm,
+		transport:  transport,
+		deviceUser: deviceUser,
+		callback:   cb,
+	}
+
+	return dev, nil
+}
+
+// ConfigureStream sets up a capture stream with the given dimensions and
+// pixel format. It allocates gralloc buffers, creates an IGBP surface
+// stub, and configures the camera for streaming.
+func (d *Device) ConfigureStream(
+	ctx context.Context,
+	width int32,
+	height int32,
+	format Format,
+) error {
+	d.width = width
+	d.height = height
+
+	// Allocate gralloc buffers.
+	for i := range d.grallocBufs {
+		buf, err := gralloc.Allocate(
+			ctx,
+			d.sm,
+			width,
+			height,
+			format,
+			gfxCommon.BufferUsageCpuReadOften|gfxCommon.BufferUsageCameraOutput,
+		)
+		if err != nil {
+			return fmt.Errorf("allocating gralloc buffer %d: %w", i, err)
+		}
+		if err := buf.Mmap(); err != nil {
+			return fmt.Errorf("mmap gralloc buffer %d: %w", i, err)
+		}
+		d.grallocBufs[i] = buf
+	}
+
+	// Begin configuration.
+	if err := d.deviceUser.BeginConfigure(ctx); err != nil {
+		return fmt.Errorf("BeginConfigure: %w", err)
+	}
+
+	// Get default request metadata.
+	metadata, err := CreateDefaultRequest(ctx, d.deviceUser, fwkDevice.TemplateIdPREVIEW)
+	if err != nil {
+		return fmt.Errorf("CreateDefaultRequest: %w", err)
+	}
+	d.metadata = metadata
+
+	// Create IGBP stub and stream.
+	d.igbpStub = cameraIGBP.NewProducerStub(uint32(width), uint32(height), d.grallocBufs)
+	igbpStubBinder := binder.NewStubBinder(d.igbpStub)
+	igbpStubBinder.RegisterWithTransport(ctx, d.transport)
+
+	streamID, err := CreateStreamWithSurface(ctx, d.deviceUser, d.transport, igbpStubBinder, width, height)
+	if err != nil {
+		return fmt.Errorf("CreateStream: %w", err)
+	}
+	d.streamID = streamID
+
+	// End configuration.
+	if err := d.deviceUser.EndConfigure(
+		ctx,
+		fwkDevice.StreamConfigurationModeNormalMode,
+		fwkDevice.CameraMetadata{Metadata: []byte{}},
+		0,
+	); err != nil {
+		return fmt.Errorf("EndConfigure: %w", err)
+	}
+
+	return nil
+}
+
+// CaptureFrame captures a single frame and returns the raw pixel data.
+// The caller should have called ConfigureStream first. This method
+// submits a repeating capture request on the first call, then reads
+// from the IGBP queue channel on subsequent calls.
+func (d *Device) CaptureFrame(
+	ctx context.Context,
+) ([]byte, error) {
+	if d.igbpStub == nil {
+		return nil, fmt.Errorf("stream not configured; call ConfigureStream first")
+	}
+
+	// Submit a repeating capture request (only needs to happen once,
+	// but submitting again is harmless and simplifies the API).
+	captureReq := fwkDevice.CaptureRequest{
+		PhysicalCameraSettings: []fwkDevice.PhysicalCameraSettings{
+			{
+				Id: "0",
+				Settings: fwkDevice.CaptureMetadataInfo{
+					Tag:      fwkDevice.CaptureMetadataInfoTagMetadata,
+					Metadata: fwkDevice.CameraMetadata{Metadata: d.metadata},
+				},
+			},
+		},
+		StreamAndWindowIds: []fwkDevice.StreamAndWindowId{
+			{StreamId: d.streamID, WindowId: 0},
+		},
+	}
+
+	_, err := SubmitRequest(ctx, d.deviceUser, captureReq, true)
+	if err != nil {
+		// Fallback to single shot.
+		_, err = SubmitRequest(ctx, d.deviceUser, captureReq, false)
+		if err != nil {
+			return nil, fmt.Errorf("SubmitRequestList: %w", err)
+		}
+	}
+
+	// Wait for a frame to be queued.
+	select {
+	case <-ctx.Done():
+		return nil, ctx.Err()
+	case slot := <-d.igbpStub.QueuedFrames():
+		buf := d.igbpStub.SlotBuffer(slot)
+		if buf == nil || buf.MmapData == nil {
+			return nil, fmt.Errorf("slot %d has no mmap'd buffer", slot)
+		}
+		// Return a copy so the caller owns the data.
+		frame := make([]byte, len(buf.MmapData))
+		copy(frame, buf.MmapData)
+		return frame, nil
+	}
+}
+
+// Close disconnects from the camera device and releases gralloc buffers.
+func (d *Device) Close(ctx context.Context) error {
+	var errs []error
+
+	if d.deviceUser != nil {
+		if err := d.deviceUser.Disconnect(ctx); err != nil {
+			errs = append(errs, fmt.Errorf("disconnect: %w", err))
+		}
+	}
+
+	for _, buf := range d.grallocBufs {
+		if buf != nil {
+			buf.Munmap()
+		}
+	}
+
+	return errors.Join(errs...)
+}

camera/device_callback.go

@@ -0,0 +1,61 @@
+// Package camera provides a high-level API for capturing frames from an
+// Android camera via binder.
+package camera
+
+import (
+	"context"
+	"sync"
+
+	fwkDevice "github.com/xaionaro-go/binder/android/frameworks/cameraservice/device"
+)
+
+// deviceCallback implements fwkDevice.ICameraDeviceCallback, tracking
+// how many frames the camera service has started processing.
+type deviceCallback struct {
+	mu             sync.Mutex
+	framesReceived int
+}
+
+func (c *deviceCallback) OnCaptureStarted(
+	_ context.Context,
+	_ fwkDevice.CaptureResultExtras,
+	_ int64,
+) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.framesReceived++
+	return nil
+}
+
+func (c *deviceCallback) OnDeviceError(
+	_ context.Context,
+	_ fwkDevice.ErrorCode,
+	_ fwkDevice.CaptureResultExtras,
+) error {
+	return nil
+}
+
+func (c *deviceCallback) OnDeviceIdle(_ context.Context) error {
+	return nil
+}
+
+func (c *deviceCallback) OnPrepared(_ context.Context, _ int32) error {
+	return nil
+}
+
+func (c *deviceCallback) OnRepeatingRequestError(
+	_ context.Context,
+	_ int64,
+	_ int32,
+) error {
+	return nil
+}
+
+func (c *deviceCallback) OnResultReceived(
+	_ context.Context,
+	_ fwkDevice.CaptureMetadataInfo,
+	_ fwkDevice.CaptureResultExtras,
+	_ []fwkDevice.PhysicalCaptureResultInfo,
+) error {
+	return nil
+}

camera/format.go

@@ -0,0 +1,11 @@
+package camera
+
+import gfxCommon "github.com/xaionaro-go/binder/android/hardware/graphics/common"
+
+// Format identifies a pixel format for camera capture.
+type Format = gfxCommon.PixelFormat
+
+// Supported pixel formats for camera capture.
+const (
+	FormatYCbCr420 Format = gfxCommon.PixelFormatYcbcr420888
+)

camera/gralloc/allocate.go

@@ -0,0 +1,58 @@
+package gralloc
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/xaionaro-go/binder/android/hardware/graphics/allocator"
+	gfxCommon "github.com/xaionaro-go/binder/android/hardware/graphics/common"
+	"github.com/xaionaro-go/binder/servicemanager"
+)
+
+// Allocate allocates a gralloc buffer using the IAllocator HAL service.
+// The returned Buffer contains a dmabuf FD that can be mmap'd for CPU
+// read access.
+func Allocate(
+	ctx context.Context,
+	sm *servicemanager.ServiceManager,
+	width int32,
+	height int32,
+	format gfxCommon.PixelFormat,
+	usage gfxCommon.BufferUsage,
+) (*Buffer, error) {
+	svc, err := sm.GetService(ctx, "android.hardware.graphics.allocator.IAllocator/default")
+	if err != nil {
+		return nil, fmt.Errorf("get allocator service: %w", err)
+	}
+
+	proxy := allocator.NewAllocatorProxy(svc)
+
+	desc := allocator.BufferDescriptorInfo{
+		Name:              []byte("camera-buffer"),
+		Width:             width,
+		Height:            height,
+		LayerCount:        1,
+		Format:            format,
+		Usage:             usage,
+		ReservedSize:      0,
+		AdditionalOptions: []gfxCommon.ExtendableType{},
+	}
+
+	result, err := proxy.Allocate2(ctx, desc, 1)
+	if err != nil {
+		return nil, fmt.Errorf("Allocate2: %w", err)
+	}
+
+	if len(result.Buffers) == 0 {
+		return nil, fmt.Errorf("Allocate2 returned 0 buffers")
+	}
+
+	return &Buffer{
+		Handle: result.Buffers[0],
+		Stride: result.Stride,
+		Width:  uint32(width),
+		Height: uint32(height),
+		Format: int32(format),
+		Usage:  uint64(usage),
+	}, nil
+}

camera/gralloc/buffer.go

@@ -0,0 +1,50 @@
+// Package gralloc provides gralloc buffer allocation via the Android
+// IAllocator HAL service.
+package gralloc
+
+import (
+	"fmt"
+
+	common "github.com/xaionaro-go/binder/android/hardware/common"
+
+	"golang.org/x/sys/unix"
+)
+
+// Buffer holds a gralloc-allocated buffer with its NativeHandle.
+type Buffer struct {
+	Handle common.NativeHandle
+	Stride int32
+	Width  uint32
+	Height uint32
+	Format int32
+	Usage  uint64
+
+	// MmapData holds a persistent mmap of the dmabuf, set by Mmap().
+	// Keeping it mapped avoids mmap/munmap syscalls per frame read.
+	MmapData []byte
+}
+
+// Mmap creates a persistent read-only mmap of this buffer's dmabuf FD.
+// The MmapData field can then be read directly. Call Munmap to release.
+func (b *Buffer) Mmap() error {
+	if len(b.Handle.Fds) == 0 {
+		return fmt.Errorf("no FDs in gralloc buffer")
+	}
+	fd := int(b.Handle.Fds[0])
+	// YCbCr_420_888: Y plane (w*h) + CbCr interleaved (w*h/2).
+	bufSize := int(b.Width) * int(b.Height) * 3 / 2
+	data, err := unix.Mmap(fd, 0, bufSize, unix.PROT_READ, unix.MAP_SHARED)
+	if err != nil {
+		return fmt.Errorf("mmap fd=%d size=%d: %w", fd, bufSize, err)
+	}
+	b.MmapData = data
+	return nil
+}
+
+// Munmap releases the persistent mmap created by Mmap.
+func (b *Buffer) Munmap() {
+	if b.MmapData != nil {
+		_ = unix.Munmap(b.MmapData)
+		b.MmapData = nil
+	}
+}