gralloc

Documentation

Overview

Package gralloc provides gralloc buffer allocation and CPU mapping via the Android IAllocator/IMapper HAL services.

Index

• func BytesPerPixel(format gfxCommon.PixelFormat) int
• type Buffer
  • func Allocate(ctx context.Context, sm *servicemanager.ServiceManager, width int32, ...) (*Buffer, error)
  • func ReadGraphicBuffer(p *parcel.Parcel) (*Buffer, error)
  • func (b *Buffer) BufferSize() int
  • func (b *Buffer) Mmap() error
  • func (b *Buffer) Munmap()
  • func (b *Buffer) ReadPixels() ([]byte, error)
• type Mapper
  • func GetMapper() (Mapper, error)

Functions

func BytesPerPixel

func BytesPerPixel(format gfxCommon.PixelFormat) int

BytesPerPixel returns the bytes per pixel for common formats. Returns 0 for planar formats (YCbCr) where bytes-per-pixel is not a meaningful concept.

Types

type Buffer

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
	// contains filtered or unexported fields
}

Buffer holds a gralloc-allocated buffer with its NativeHandle.

func Allocate

func Allocate(
	ctx context.Context,
	sm *servicemanager.ServiceManager,
	width int32,
	height int32,
	format gfxCommon.PixelFormat,
	usage gfxCommon.BufferUsage,
) (*Buffer, error)

Allocate allocates a gralloc buffer using the best available allocator. The fallback chain is:

1. AIDL IAllocator (android.hardware.graphics.allocator.IAllocator/default)
2. HIDL gralloc 3.0 IAllocator via hwbinder
3. dma-buf heap (/dev/dma_heap/system)
4. memfd (last resort; camera HAL may not accept these)

func ReadGraphicBuffer

func ReadGraphicBuffer(p *parcel.Parcel) (*Buffer, error)

ReadGraphicBuffer reads a flattened GraphicBuffer from a parcel. The wire format follows GraphicBuffer::unflatten():

int32(flattenedSize) + int32(fdCount) + raw[flattenedSize] + fd objects

func (*Buffer) BufferSize

func (b *Buffer) BufferSize() int

BufferSize returns the buffer size in bytes based on dimensions and pixel format.

func (*Buffer) Mmap

func (b *Buffer) Mmap() error

Mmap creates a persistent mmap of this buffer's dmabuf FD. It tries several flag combinations to handle different allocator backends (AIDL gralloc, HIDL gralloc, dma-buf heap, memfd). On kernel 6.6+, DMA-BUF mmap requires a prior SYNC ioctl. The MmapData field can then be read directly. Call Munmap to release.

For goldfish emulator buffers (/dev/goldfish_address_space), the FD requires claiming a shared region via ioctl and mmapping at the buffer's address space offset. The mapped data reflects whatever the host GPU has written; after the camera HAL queues a buffer (which calls rcReadColorBuffer internally), the pixels are readable. If the goldfish path fails, ReadPixels() falls back to the IMapper bridge (gralloc_bridge.so).

func (*Buffer) Munmap

func (b *Buffer) Munmap()

Munmap releases the persistent mmap created by Mmap.

func (*Buffer) ReadPixels

func (b *Buffer) ReadPixels() ([]byte, error)

ReadPixels returns the buffer pixel data. When MmapData is available (memfd, dma-buf heap, or compatible gralloc), a copy of the mapped data is returned. When mmap is unavailable (goldfish emulator), falls back to the HIDL IMapper HAL via gralloc_bridge.so.

type Mapper

type Mapper interface {
	LockBuffer(b *Buffer) ([]byte, error)
}

Mapper provides CPU access to gralloc buffers.

func GetMapper

func GetMapper() (Mapper, error)

GetMapper returns a Mapper for the current device. The result is cached. Returns (nil, nil) when no mapper is available (real devices where mmap works directly).