OFX : Fields and Field Rendering

Fields are evil, but until the world decides to adopt sensible video standard and casts the current ones into the same pit as 2 inch video tape, we are stuck with them.

Before we start, some nomenclature. The Y-Axis is considerred to be up, so in a fielded image,

  • even scan lines 0,2,4,6,... are collectively referred to as the lower field,
  • odd scan lines 1,3,5,7... are collective referred to as the upper field.

We don't call them odd and even, so as to avoid confusion with video standard, which have scanline 0 at the top, and so have the opposite sense of our 'odd' and 'even'.

Clips and images from those clips are flagged as to whether they are fielded or not, and if so what is the spatial/temporal ordering of the fields in that image. The kOfxImageClipPropFieldOrder clip and image instance property can be...

  • kOfxImageFieldNone - the material is unfielded
  • kOfxImageFieldLower - the material is fielded, with scan line 0,2,4.... occuring first in a frame
  • kOfxImageFieldUpper - the material is fielded, with scan line 1,3,5.... occuring first in a frame

Images extracted from a clip flag what their fieldedness is with the property kOfxImagePropField , this can be....

  • kOfxImageFieldNone - the image is an unfielded frame
  • kOfxImageFieldBoth - the image is fielded and contains both interlaced fields
  • kOfxImageFieldLower - the image is fielded and contains a single field, being the lower field (lines 0,2,4...)
  • kOfxImageFieldUpper - the image is fielded and contains a single field, being the upper field (lines 1,3,5...)

The plugin specifies how it deals with fielded imagery by setting the kOfxImageEffectPluginPropFieldRenderTwiceAlways property. This can be,

  • 0 - the plugin is to have it's render function called twice only if there is animation in any of it's parameters
  • 1 - the plugin is to have it's render function called twice always (default)

The reason for this is an optimisation. Imagine a text generator with no animation being asked to render into a fielded output clip, it can treat an interlaced fielded image as an unfielded frame. So the host can get the effect to render both fields in one hit and save on the overhead required to do the rendering in two passes.

If called twice per frame, the time passed to the render action will be frame and frame+0.5. So 0.0 0.5 1.0 1.5 etc...

When rendering unfielded footage, the host will only ever call the effect's render action once per frame, with the time being at the integers, 0.0, 1.0, 2.0 and so on.

The render action's argument property kOfxImageEffectPropFieldToRender tells the effect which field it should render, this can be one of...

  • kOfxImageFieldNone - there are no fields to deal with, the image is full frame
  • kOfxImageFieldBoth - the imagery is fielded and both scan lines should be renderred
  • kOfxImageFieldLower - the lower field is being rendered (lines 0,2,4...)
  • kOfxImageFieldUpper - the upper field is being rendered (lines 1,3,5...)


kOfxImageEffectPropFieldToRender will be set to kOfxImageFieldBoth if kOfxImageEffectPluginPropFieldRenderTwiceAlways is set to 0 on the plugin,

A plugin can specify how it wishes fielded footage to be fetched from a clip via the clip descriptor property kOfxImageClipPropFieldExtraction . This can be one of...

  • kOfxImageFieldBoth fetch a full frame interlaced image
  • kOfxImageFieldSingle fetch a single field, making a half height image
  • kOfxImageFieldDoubled fetch a single field, but doubling each line and so making a full height image (default)

If fetching a single field, the actual field fetched from the source frame is...

  • the first temporal field if the time passed to clipGetImage has a fractional part of 0.0 <= f < 0.5
  • the second temporal field otherwise,

To illustrate this last behaviour, the two examples below show an output with twice the frame rate of the input and how clipGetImage maps to the input. The .0 and .5 mean first and second temporal fields.

Behaviour with unfielded footage

output 0       1       2       3
source 0       0       1       1
Behaviour with fielded footage

output 0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5            
source 0.0 0.0 0.5 0.5 1.0 1.0 1.5 1.5


  • while some rarely used video standards can have odd number of scan-lines, under OFX, both fields always consist of the same number of lines. Pad with black where needed.
  • host developers, for single field extracted images, you don't need to do any buffer copies, you just need to set the row bytes property of the returned image to twice the normal value, and maybe tweak the start address by a scanline.