Command: Pause a cog's execution until its Video Generator is available to take pixel data.

((PUB ┆ PRI))
   WAITVID (Colors, Pixels )

• Colors is a long containing four byte-sized color values, each describing the four possible colors of the pixel patterns in Pixels.
• Pixels is the next 16-pixel by 2-bit (or 32-pixel by 1-bit) pixel pattern to display.

Explanation

WAITVID, "Wait for Video Generator," is one of four wait commands (WAITCNT, WAITPEQ, WAITPNE, and WAITVID) used to pause execution of a cog until a condition is met. WAITVID pauses the cog until its Video Generator hardware is ready for the next pixel data, then the Video Generator accepts that data and the cog continues execution with the next line of code.

When executed, WAITVID activates special "wait" hardware in the cog that prevents the System Clock from causing further code execution within the cog until the moment the Video Generator is ready. The wait hardware checks the Video Generator's status every System Clock cycle and the cog's power consumption is reduced significantly during this time.

Using WAITVID

WAITVID is simply a delivery mechanism for data to the cog's Video Generator hardware. Since the Video Generator works independently from the cog itself, the two must synchronize each time data is needed for the display device. The frequency at which this occurs depends on the display device and the corresponding settings for the Video Generator, but in every case, the cog must have new data available the moment the Video Generator is ready for it. The cog uses the WAITVID command to wait for the right time and then "hand off" this data to the Video Generator.

The Colors parameter is a 32-bit value containing either four 8-bit color values (for 4-color mode) or two 8-bit color values in the lower 16 bits (for 2-color mode). For VGA, each color value's upper 6-bits is the 2-bit red, 2-bit green, and 2-bit blue color components describing the desired color; the lower 2-bits are "don't care" bits. Each of the color values corresponds to one of the four possible colors per 2-bit pixel (when Pixels is used as a 16x2 bit pixel pattern) or as one of the two possible colors per 1-bit pixel (when Pixels is used at a 32x1 bit pixel pattern).

Pixels describes the pixel pattern to display, either 16 pixels or 32 pixels depending on the color-depth configuration of the Video Generator.

Review the TV and VGA objects for examples of how WAITVID is used.

Make sure to start the cog's Video Generator module and Counter A before executing the WAITVID command or it will wait forever. See VCFG, VSCL, and CTRA, CTRB.