camera_frame_bayer

A frame descriptor for a Bayer frame type

Synopsis:

#include <camera/camera_api.h>

typedef struct {
    uint64_t bufsize;
    uint32_t height;
    uint32_t width;
    uint32_t stride;
    camera_bayerformat_t format;
    uint32_t packing;
    uint32_t bpp;
    bool le;
    uint32_t cadence_length;
    uint32_t pixels_per_cadence;
    camera_bayerjustify_t justification;
} camera_frame_bayer_t;

Data:

uint64_t bufsize: The size of the frame, in bytes.
uint32_t height: The height of the frame, in pixels.
uint32_t width: The width of the frame, in pixels.
uint32_t stride: The number of bytes, in memory, between the first pixel of the first row and the first pixel of the second row.
Stride is often called pitch.
camera_bayerformat_t format: The format of the Bayer array macro-pixel (see camera_bayerformat_t).
uint32_t packing: The inter-pixel stride, in bits.
uint32_t bpp: The bits-per-pixel component inside the packing size.
bool le: Whether little-endian is used to pack the frame.
When le is true, the bytes are packed in little-endian; when le is false, the bytes are packed in big-endian.
uint32_t cadence_length: The size, in bits, of a packing cadence.
uint32_t pixels_per_cadence: The number of pixels in a packing cadence.
camera_bayerjustify_t justification: The justification of the pixel bits (see camera_bayerjustify_t).

Library:

libcamapi

Description:

Use this frame descriptor when CAMERA_FRAMETYPE_BAYER is reported as the camera_frametype_t.

In the Bayer frame, each Bayer macro-pixel is made up of four color components: one red, one blue, and two green. We refer to individual color components as pixels, and the group of four as a macro-pixel.

Each macro-pixel is stored across two lines in the frame. The first two color component pixels are stored contiguously on the first line. The stride separates the first pixel from the third, and the second pixel from the fourth.

Each pixel comprises bpp bits. These bits can be packed into larger-sized words of a size indicated by packing. In addition, groups of pixels may be tightly packed into a cadence, which is defined by cadence_length and pixels_per_cadence. The ordering of the bits is determined by the justification field.

Examples:

Example 1:

 le = true
 bpp = 10
 packing = 16
 cadence_length = 16
 pixels_per_cadence = 1
 justification = CAMERA_BAYERJUSTIFY_RIGHT_BIT0LSB
 format = CAMERA_BAYERFORMAT_RGGB

This example describes a 10-bit Bayer frame where each color component is stored as 10 bits packed into 16-bit words. Each word is stored in little-endian byte order. Bit 0 represents the least significant bit, and the bits are justified to the right of each byte. This leaves six unused bits per pixel.

The Bayer macro-pixels in one cadence would be stored like so, with PxHi indicating the most significant bits of pixel x, and PxLo indicating the least significant bits of pixel x:

 Bit:                  76543210
 Scanline n,   byte 0: RRRRRRRR    P1Lo(Red)
 Scanline n,   byte 1: 000000RR    P1Hi(Red)
 Scanline n,   byte 2: GGGGGGGG    P2Lo(Green)
 Scanline n,   byte 3: 000000GG    P2Hi(Green)
 ...and repeats.

 Scanline n+1, byte 0: GGGGGGGG    P1Lo(Green)
 Scanline n+1, byte 1: 000000GG    P1Hi(Green)
 Scanline n+1, byte 2: BBBBBBBB    P2Lo(Blue)
 Scanline n+1, byte 3: 000000BB    P2Hi(Blue)
 ...and repeats.

Example 2:

 le = false
 bpp = 10
 packing = 10
 justification = CAMERA_BAYERJUSTIFY_LEFT_BIT0LSB
 cadence_length = 10
 pixels_per_cadence = 1
 format = CAMERA_BAYERFORMAT_RGGB

This example describes a 10-bit Bayer frame where each 10-bit pixel is tightly packed into a 10-bit word. There are no wasted bits in between pixels in this example. Each word is stored in big-endian byte order. Bit 0 represents the least significant bit, and the bits are justified to the left of each byte.

The Bayer macro-pixels in one cadence would be stored like so, with PxHi indicating the most significant bits of pixel x, and PxLo indicating the least significant bits of pixel x:

 Bits:                 76543210
 Scanline n,   byte 0: RRRRRRRR    P1Hi(Red)
 Scanline n,   byte 1: RRGGGGGG    P1Lo(Red)     & P2Hi(Green)
 Scanline n,   byte 2: GGGGRRRR    P2Lo(Green)   & P3Hi(Red)
 Scanline n,   byte 3: RRRRRRGG    P3Lo(Red)     & P4Hi(Green)
 Scanline n,   byte 4: GGGGGGGG    P4Lo(Green)
 ...and repeats.

 Scanline n+1, byte 0: GGGGGGGG    P1Hi(Green)
 Scanline n+1, byte 1: GGBBBBBB    P1Lo(Green)   & P2Hi(Blue)
 Scanline n+1, byte 2: BBBBGGGG    P2Lo(Blue)    & P3Hi(Green)
 Scanline n+1, byte 3: GGGGGGBB    P3Lo(Green)   & P4Hi(Blue)
 Scanline n+1, byte 4: BBBBBBBB    P4Lo(Blue)
 ...and repeats.

Example 3:

 le = true
 bpp = 10
 packing = 10
 justification = CAMERA_BAYERJUSTIFY_RIGHT_BIT0LSB
 cadence_length = 64
 pixels_per_cadence = 6
 format = CAMERA_BAYERFORMAT_RGGB

This example describes a 10-bit Bayer frame where each 10-bit pixel is tightly packed into a 10-bit word, and six pixels are packed into a 64-bit cadence. Each word is stored in little-endian byte order. Bit 0 represents the least significant bit and the bits are justified to the right of each byte. This leaves four unused bits for each six-pixel cadence.

The Bayer macro-pixels in one cadence would be stored like so, with PxHi indicating the most significant bits of pixel x, and PxLo indicating the least significant bits of pixel x:

 Bits:                 76543210
 Scanline n,   byte 0: RRRRRRRR    P1Lo(Red)
 Scanline n,   byte 1: GGGGGGRR    P2Lo(Green)   & P1Hi(Red)
 Scanline n,   byte 2: RRRRGGGG    P3Lo(Red)     & P2Hi(Green)
 Scanline n,   byte 3: GGRRRRRR    P4Lo(Green)   & P3Hi(Red)
 Scanline n,   byte 4: GGGGGGGG    P4Hi(Green)
 Scanline n,   byte 5: RRRRRRRR    P5Lo(Red)
 Scanline n,   byte 6: GGGGGGRR    P6Lo(Green)   & P5Hi(Red)
 Scanline n,   byte 7: 0000GGGG    4 bits unused & P6Hi(Green)
 ...and repeats.

 Scanline n+1, byte 0: GGGGGGGG    P1Lo(Green)
 Scanline n+1, byte 1: BBBBBBGG    P2Lo(Blue)    & P1Hi(Green)
 Scanline n+1, byte 2: GGGGBBBB    P3Lo(Green)   & P2Hi(Blue)
 Scanline n+1, byte 3: BBGGGGGG    P4Lo(Blue)    & P3Hi(Green)
 Scanline n+1, byte 4: BBBBBBBB    P4Hi(Blue)
 Scanline n+1, byte 5: GGGGGGGG    P5Lo(Green)
 Scanline n+1, byte 6: BBBBBBGG    P6Lo(Blue)    & P5Hi(Green)
 Scanline n+1, byte 7: 0000BBBB    4 bits unused & P6Hi(Blue)
 ...and repeats.

Note:

Looking at Scanline n, byte 1, you should see that the P1Hi bits (the most significant bits of pixel 1) begin at the right of the byte. The reason is because right justification is indicated by CAMERA_BAYERJUSTIFY_RIGHT_BIT0LSB. This example is in contrast to Example 2 where the bits are justified to the left and occupy the upper bits of Scanline n, byte 1.