ref_struct_VDXPixmap - shekh/VirtualDub2 GitHub Wiki

VirtualDub Plugin SDK 1.2

VDXPixmap structure

Declares a pixel map (pixmap). This is sometimes also called a bitmap.

struct VDXPixmap {
    void            *data;
    const uint32    *palette;
    sint32          w;
    sint32          h;
    ptrdiff_t       pitch;
    sint32          format;

    // Auxiliary planes are always byte-per-pixel.
    void            *data2;     // Cb (U) for YCbCr
    ptrdiff_t       pitch2;
    void            *data3;     // Cr (V) for YCbCr
    ptrdiff_t       pitch3;
};

data
Pointer to the start of the first scanline in the primary plane. This must be aligned to the smallest natural alignment for the pixel type. For instance, two-byte pixels must be aligned to a 16-bit boundary, and four-byte pixels must be aligned to a 32-bit boundary. 24-bit pixels require no special alignment.

palette
For paletted formats, a pointer to 32-bit XRGB8888 palette entries. The alpha component is ignored.

w
Width of the primary plane, in pixels. This must be greater than zero.

h
Height of the primary plane, in pixels. This must be greater than zero.

pitch
The difference in bytes between the address of the start of one scanline and the next in the primary plane. This may be zero or negative. The pitch must maintain alignment across scanlines — a pixmap with 16-bit pixels may not use an odd pitch.

format
Format and color space of pixels in the pixmap.

data2
For formats with secondary planes, the start of the first scanline in plane 2.

pitch2
For formats with secondary planes, the difference in bytes between the address of the start of one scanline and the next in plane 2. This may be zero or negative.

data3
For formats with secondary planes, the start of the first scanline in plane 3.

pitch3
For formats with secondary planes, the difference in bytes between the address of the start of one scanline and the next in plane 3. This may be zero or negative.

Most formats only have a primary plane and thus only use data and pitch. YCbCr formats with three planes use the secondary planes as well; Cb (U) is plane 2 and Cr (V) is plane 3. The secondary planes always have the same size, but may be of different size than the primary plane depending on the format. All three planes may have different pitches.

Scanlines should not overlap in pixmaps passed as destinations, but it is OK to do so for sources; in particular, a pitch of zero simply repeats one scanline down the entire image. Buffers should be declared with non-overlapping scanlines.

For formats that use subsampled secondary planes, such as 4:2:0 planar YCbCr, the pixmap must be sized such that the secondary planes consist of an integral number of samples. For instance, a 4:2:0 pixmap may have a size of 320x240, which leads to 160x120 secondary planes. It cannot have a size of 319x240, because this would lead to a secondary size of 159.5x120. The main reason for this restriction is due to a lack of consensus as to how this situation should be treated; some video drivers and codecs round up, some round down, some display garbage, and some just crash. For best compatibility, it is recommended that if this situation is encountered in the underlying file format that the subsampled formats be disabled or that the video be padded to the next non-problematic size.

In the original VirtualDub video filter API, the VBitmap structure's data field pointed to the bottom scanline, and a positive pitch meant bottom-up storage. VDXPixmap is reversed so that data points to the top scanline and a positive pitch indicates top-down storage. Pitch should therefore be negative whenever a Windows DIB compatible layout is required.

Copyright (C) 2007-2012 Avery Lee.