Chapter 8. Images and Clips

What Is An Image?

Image Effects process images (funny that), this chapeter describes images and clips of images, how they behave and how to deal with them.

Firstly some definitions...

  • an image is a rectangular array of addressable pixels,
  • a clip is a contiguous sequence of images that vary over time.

Images and clips contain pixels, these pixels can currently be of the following types...

  • a colour pixel with red, green, blue, alpha components
  • a colour pixel with red, green and blue components
  • single component 'alpha' images

The components of the pixels can be of the following types...

  • 8 bit unsigned byte, with the nominal black and white points at 0 and 255 respectively,
  • 16 bit unsigned short, with the nominal black and white points at 0 and 65535 respectively,
  • 32 bit float, with the nominal black and white points at 0.0f and 1.0f respectively, component values are not clipped to 0.0f and 1.0f.

Components are packed per pixel in the following manner...

  • RGBA pixels as R, G, B, A
  • RGB pixels as R, G, B

There are several structs for pixel types in ofxCore.h that can be used for raw pixels in OFX.

Images are always left to right, bottom to top, with the pixel data pointer being at the bottom left of the image. The pixels in a scan line are contiguously packed.

Scanlines need not be contiguously packed. The number of bytes between between a pixel in the same column, but separated by a scan line is known as the rowbytes of an image. Rowbytes can be negative, allowing for compositing systems with a native top to bottom scanline order to trivially support bottom to top images.

Clips and images also have a pixel aspect ratio , this is how much an actual addressable pixel must be stretched by in X to be square. For example PAL SD images have a pixel aspect ratio of 1.06666.

Images are rectangular, whose integral bounds are in Pixel coordinates, with the image being X1 <= X < X2 and Y1 <= Y < Y2, ie: exclusive on the top and right. The bounds represent the amount of data present in the image, which may be larger, smaller or equal to the Region of Definition of the image, depending on the architecture supported by the plugin. The kOfxImagePropBounds property on an image holds this information.

An image also contains it's RoD in image coordinates, in the kOfxImagePropRegionOfDefinition property. The RoD is the maximum area that an image may have pixels in, t he bounds are the actual addressable pixels present in an image. This allows for tiled rendering an so on.

Clips have a frame rate, which is the number of frames per second they are to be displayed at. Some clips may be continously samplable (for example, if they are connected to animating geometry that can be rendered at arbitrary times), if this is so, the frame rate for these clips is set to 0.

Images may be composed of full frames, two fields or a single field, depending on its source and how the effect requests the image be processed. Clips are either full frame sequences or fielded sequences.

Images and clips also have a premultiplication state, this represents how the alpha component and the RGB/YUV components may have interacted.