go4vl

To benefit from the performance improvements of GetFrames(), you must strictly follow the frame lifecycle to prevent pool exhaustion:

1. Receive: Iterate over the channel returned by dev.GetFrames().
2. Process: Use frame.Data to perform your work.
3. Release: You MUST call frame.Release() when finished with the frame. This returns the buffer to the pool for reuse.

Critical Warnings:

• Do not use frame.Data after calling Release(): The buffer is immediately invalid and may be overwritten by the next captured frame.
• Copy if you need to persist data: If you need to use the frame data outside the capture loop, you must copy it to a new slice before calling Release().
• Failure to call Release(): If you forget to release frames, the buffer pool will eventually exhaust, causing the application to stall or crash.

// GOOD: Copy before Release() to use data later
frame := <-dev.GetFrames()
saved := make([]byte, len(frame.Data))
copy(saved, frame.Data)
frame.Release()
processLater(saved) // OK: using copy

For stateless codec parameters (H.264, MPEG2, VP8, FWHT), go4vl provides type-safe helper methods. Instead of manually marshaling byte slices, you can use Go structs and specialized Add... and Get... methods. This provides compile-time checking and better IDE support.

Supported Codec Helpers

H.264 Stateless Codec:

• AddH264SPS() / GetH264SPS()
• AddH264PPS() / GetH264PPS()
• AddH264ScalingMatrix() / GetH264ScalingMatrix()
• AddH264SliceParams() / GetH264SliceParams()
• AddH264DecodeParams() / GetH264DecodeParams()
• AddH264PredWeights() / GetH264PredWeights()

MPEG2 Stateless Codec:

• AddMPEG2Sequence() / GetMPEG2Sequence()
• AddMPEG2Picture() / GetMPEG2Picture()
• AddMPEG2Quantization() / GetMPEG2Quantization()

VP8 Stateless Codec:

• AddVP8Frame() / GetVP8Frame()

FWHT Stateless Codec:

• AddFWHTParams() / GetFWHTParams()

// Example: Setting H.264 SPS using type-safe API
dev, _ := device.Open("/dev/video0")
defer dev.Close()

ctrls := v4l2.NewExtControls()

sps := &v4l2.ControlH264SPS{
    ProfileIDC:              100, // High Profile
    LevelIDC:                51,  // Level 5.1
    ChromaFormatIDC:         1,   // 4:2:0
    Log2MaxFrameNumMinus4:   0,
    PicOrderCntType:         0,
    Log2MaxPicOrderCntLsbMinus4: 2,
    MaxNumRefFrames:         4,
    PicWidthInMbsMinus1:     119, // 1920 pixels
    PicHeightInMapUnitsMinus1: 67, // 1080 pixels
}
ctrls.AddH264SPS(sps)

err := dev.SetExtControls(ctrls)
if err != nil {
    log.Fatalf("Failed to set H.264 controls: %v", err)
}

V4L2 organizes device parameters into specific classes. Understanding these helps in targeting the correct controls.

Control Classes

Control Types

Controls can be of several types:

• Integer: Numeric value with range and step.
• Boolean: True/false (0/1).
• Menu: Selection from named options.
• Button: Triggers an action.
• Integer64: 64-bit numeric value.
• String: Text value.
• Bitmask: Bitfield value.
• IntegerMenu: Selection from numeric options.
• U8/U16/U32: Array controls.

The webcam example demonstrates a pattern for streaming video frames to a web page using the go4vl API:

1. Open the device: Use device.Open with configuration options like WithIOType, WithPixFormat, and WithFPS.
2. Start capture: Call device.Start(ctx) to begin streaming. Use defer device.Close() to ensure resources are released.
3. Retrieve frames: Access the stream of video buffers via device.GetOutput(), which returns a <-chan []byte.
4. Serve via HTTP: Use an HTTP handler to stream the frames using the multipart/x-mixed-replace content type. This allows the browser to render the sequence of JPEG buffers as a continuous video stream.

// 1. Open device
device, err := device.Open(devName,
    device.WithIOType(v4l2.IOTypeMMAP),
    device.WithPixFormat(v4l2.PixFormat{PixelFormat: getFormatType(format), Width: uint32(width), Height: uint32(height)}),
    device.WithFPS(uint32(frameRate)), 
)

// 2. Start capture
ctx, cancel := context.WithCancel(context.TODO())
if err := device.Start(ctx); err != nil {
    log.Fatalf("stream capture: %s", err)
}
defer func() {
    cancel()
    device.Close()
}()

// 3. Get output channel
frames := device.GetOutput()

// 4. Serve via HTTP (simplified logic)
for frame := range frames {
    // Write multipart boundary and JPEG headers, then the frame bytes
    io.WriteString(w, fmt.Sprintf("--%s\n", boundaryName))
    io.WriteString(w, "Content-Type: image/jpeg\n")
    io.WriteString(w, fmt.Sprintf("Content-Length: %d\n\n", len(frame)))
    w.Write(frame)
    io.WriteString(w, "\n")
}