The YMF Image Format

Because PGL operates in a distributed memory environment and needs to communicate image streams across the network in something approaching real time, existing image formats are not well-suited to the application. Hence PGL has its own image format, called Y Movie Format, or just YMF.

The "Y" derives from the fact that YMF allows scanlines to be tagged with their scanline number (y address), which means they can be stored in arbitrary order within the image file. This property allows more flexibility in the parallel rendering and display algorithms employed by PGL, resulting in faster display rates and reduced memory requirements.

The "Movie" part of the name implies a sequence of images, and YMF uses frame-to-frame differencing and run-length encoding to achieve fast, lossless image compression and decompression.

Several conversion utilities are provided to transform YMF images into other common formats. These utilities also allow individual frames, or sequences of frames, to be extracted from YMF files.

YMF combines and adapts concepts from several other image/animation formats, including X Window Dump (XWD), AutoDesk Animator Flic (FLI), and NASA Langley Raster Metafile (RM). YMF supports either of two color encodings. In X11 terminology these are (1) single-channel 8-bit colormapped PseudoColor, or (2) three-channel 24-bit (8 bits/channel) TrueColor.

YMF uses an RGB color model and run-length encodes each color channel separately. Normally, the first frame is encoded in its entirety, and each successive frame encodes only those pixels which have changed from the previous frame. While this frame-differencing usually leads to improved compression ratios, it is not required, and YMF files which encode the entire contents of every frame are perfectly legal. Thus there are memory/compression/performance trade-offs which can be made depending on the requirements of a given application. The current version of PGL always uses frame-differencing when generating YMF output streams.

YMF supports image resolutions ranging from 1-4096 in both X and Y. Thus the smallest possible image is 1 x 1 (a single pixel), and the largest is 4096 x 4096.

Structure of a YMF Data Stream

A YMF data stream starts with a YMFHeader structure, which specifies global properties such as the color encoding, frame rate, and image resolution.

The YMFHeader is followed by one or more clips. Clips may be used to supply additional internal structure to a YMF file, which may be useful, for example, when an animation contains several logically distinct segments. Clips are defined by a series of opcodes and their associated operands. All opcodes must be aligned on even byte boundaries in the input stream.

Each clip contains one or more frames. The first frame in each clip must encode the image in its entirety. Successive frames within a clip need to encode only those pixel values which differ from the previous frame. Within a frame, each color channel is encoded separately, which results in better color coherence and improved compressibility. For 24-bit color, each channel specifies the intensity of a different color component (red, green, or blue) in the range from 0-255. For 8-bit color, the single channel contains indices into a color look-up table (colormap) which contains a maximum of 256 entries.

Opcodes

All opcodes are represented as 16-bit unsigned integers. The high-order four bits identify the opcode, while the low-order 12 bits are used for addresses, operand counts, pixel values, etc.

YMF_CLP (0x2000)

Clip header. This is the first word of a new clip. It must be followed by a YMFClipHeader which specifies the background color for the clip.

YMF_TRL (0xf000)

Clip trailer. Signifies the end of a clip.

YMF_COL (0x1000)

Defines new colormap entries to be used on the next frame and all successive frames until the next YMF_COL is encountered. The low-order 8 bits specify the number of YMFColor structures which immediately follow (not to exceed 256). Each YMFColor structure specifies a single colormap entry. In the case of colormaps which are changing dynamically, YMF_COL directives need to supply only those colormap entries which have changed, rather than the entire colormap.

If not redefined, YMF_COL definitions persist across clip boundaries. YMF_COL definitions can appear anywhere within a clip after the clip header and the title, but must not appear within a frame. They may also appear outside of any clip, for those situations in which a single colormap applies globally to multiple clips.

Colormap definitions are needed only with 8-bit PseudoColor encodings, and should be omitted from 24-bit image streams.

YMF_TTL (0x0000)

Title. This opcode is optional. It may occur anywhere a YMF_COL may occur. The low-order 12 bits contain the length of the title string, including one or two trailing NULs. A NUL-terminated title string follows the YMF_TTL opcode, and must end on an even byte boundary. A second trailing NUL character may be added if necessary. Typical usage would be to define an overall title for the movie and/or subtitles for individual clips. Each new title supercedes previous titles. Titles are provided only for informational purposes; they have no effect on the content of encoded images. YMF players are free to use (or ignore) titles in any way they see fit.

YMF_SF (0x3000)

Start frame. This appears at the beginning of each frame within a clip. The first frame in each clip should contain all of the data necessary to define the entire image. Subsequent frames only need to specify that portion of the image which has changed since the previous frame. The low-order 12 bits contain no information.

YMF_EF (0xe000)

End frame. This must appear at the end of each frame. This signals that the frame is complete and ready to display. The low-order 12 bits contain no information.

YMF_SC (0x4000)

Start channel. This indicates the start of data for a color channel. The current scanline and current x offset are set to 0. The low-order 2 bits indicate the channel number (0-2). By convention, a 24-bit image uses channel 0 for red, channel 1 for green, and channel 2 for blue. An 8-bit image uses only channel 0.

YMF_EC (0xd000)

End channel. Signals the end of a color channel. The low-order 12 bits contain no information.

YMF_Y (0x5000)

The low-order 12 bits indicate a scanline number, beginning with 0 as the top line of the image. This opcode also sets the current x offset in the scanline to 0.

YMF_X (0x6000)

The low-order 12 bits indicate an x offset in the current scanline.

YMF_YR (0x7000)

Y Run. Indicates a run of scanlines of the background color, beginning with the current scanline. The low-order 12 bits specify the run length, in scanlines. The current scanline number is increased by the run length.

YMF_XR (0x8000)

X Run. Indicates a run of pixels of the background color, beginning with the current x offset in the current scanline. The low-order 12 bits specify the run length, in pixels. The current X offset is increased by the run length. An X Run must not extend past the end of the current scanline.

YMF_PXL (0x9000)

Single pixel. Indicates a single pixel at the current x offset in the current scanline. The low-order 8 bits contain the pixel's value.

YMF_PS (0xa000)

Pixel string. The following string of bytes contains pixel values, one per byte, starting at the current x offset in the current scanline. The low-order 12 bits specify the number of pixels in the string. If this is an odd number, the byte string is padded at the end to an even byte boundary. If more than three consecutive pixels have different values, this format is more compact than the equivalent YMF_PXL encoding. Pixel strings must not extend beyond the end of the current scanline.

YMF_RL (0xb000)

Run length. Indicates a run of pixels with the same value, starting at the current x offset in the current scanline. The low-order 12 bits contain the length of the run. The pixel value follows immediately with a YMF_PV opcode. Runs must not extend past the end of the current scanline.

YMF_PV (0xc000)

Pixel value. The low order 8 bits contain the pixel value for a preceding YMF_RL.

Notes

PGL supports rendering resolutions up to 32K x 32K (1 gigapixel). Because YMF opcodes provide only 12 bits of addressing, YMF cannot accommodate resolutions above 4K x 4K. The solution for extremely high-res output would be to define a companion image format tailored for that purpose. PGL is designed to allow multiple output formats, so this would be a relatively straightforward addition.

YMF files may be created in either most-significant-byte-first (MSB) or least-significant-byte-first (LSB) order. The swaptest field in the YMF header, which contains the constant value 1, can be used to determine the byte order of a YMF stream. While current YMF players (ymovie, ymfd, etc.) don't do byte-swapping (to maximize performance), this is not an inherent limitation of the YMF image format, and YMF players could easily be constructed to handle either byte order.