Chapter 6. Video Parameters

The processing of a video input/output path is described by two sets of parameters:

Not all parameters may be supported on a particular video jack or path. Note that some parameters may be adjusted on both a path and a jack, or may be adjustable on just one or the other. Use dmGetCapabilities to obtain a list of parameters supported by a jack or path. In addition, not all values may be supported on a particular parameter. Use dmPvGetCapabilities to obtain a list of the values supported by the parameter.


Note: This chapter, as well as Chapter 7, “Image Parameters” assume a working knowledge of digital video concepts. Readers unfamiliar with terms like video timing, 422 or CbYCr may wish to consult a text devoted to this subject. A good resource is A Technical Introduction to Digital Video, by Charles Poynton, published by John Wiley & Sons, 1996 (ISBN 0-471-12253-X, hardcover).


Video Sampling

There are two kinds of video sampling, spatial and temporal. Our concern here is with temporal sampling, of which there are two techniques:

  • progressive sampling is frame-based (for example, from film).

  • interlaced sampling is field-based.

Progressive Sampling


In progressive, frame-based sampling, a picture at a specified resolution is sampled at constant rate. Film is a progressive sampling source for video.

Imagine an automatic film advance camera that can take 60 pictures-per-second, with which you take a series of pictures of a moving ball. Figure 6-1 shows 10 pictures from that sequence (different colors emphasize the different positions of the ball in time). The time delay between each picture is a 60th of a second, so this sequence lasts 1/6th of a second.

Figure 6-1. Film at 60 Frames-per-Second

Film at 60 Frames-per-Second

Interlaced Sampling

Interlaced sampling is more involved than progressive sampling. Here, the video is sampled in a periodicity of two sample fields, called F1 and F2, such that half of the display lines of the picture are scanned at a time. Like window blinds, every other line in a sample field is blank.

Pairs of sample fields are superimposed on each other or “interlaced” to create the video frame. In the video frame, the sample frames, while consecutive, appear coincident to the eye. This effect is aided by the persistence of phosphors on the display screen which hold the impression of the first set of scanned lines as the second set displays. (This sequence is made visible if you videotape a computer monitor display.)

Most video signals in use today, including several high-definition video formats, are field-based (interlaced) rather than frame-based (progressive). In the dmSDK, the value of the Video Timing parameter DM_VIDEO_TIMING_INT32 defines the specific video standard, and each standard is defined as progressive or interlaced.

Example of Interlaced Sampling


Suppose you shoot the moving ball with an NTSC video camera. NTSC video has 60 fields-per-second, so you might think that the video camera would record the same series of pictures as shown in Figure 6-1, but it does not. The video camera does record 60 images per second, but each image consists of only half of the scanned lines of the complete picture at a given time, as shown in Figure 6-2, rather than a filmstrip of 10 complete images.

Note how the image lines alternate between odd- and even-numbered images.

Figure 6-2. Video at 60 Frames-per-Second

Video at 60 Frames-per-Second

Video Parameters

Parameter

Purpose

DM_VIDEO_TIMING_INT32

video timing parameter

DM_VIDEO_COLORSPACE_INT32

video colorspace parameter

DM_VIDEO_PRECISION_INT32

video precision parameter

DM_TIMING_UNKNOWN

Timing of input signal cannot be determined.

DM_TIMING_NONE

No signal present.

DM_VIDEO_TIMING_INT32


This parameter sets the timing on an input or output video path. Not all timings may be supported on all devices. On devices which can auto-detect, the timing may be read-only on input. (Details of supported timings may be obtained by calling dmPvGetCapabilites on this parameter). Figure B-1 and Figure B-2 illustrate details of the 601 standard.

Supported Timings



Note: See Appendix B, “Common Video Standards” for diagrams of common video standards.

These format for these timings are as follows:

DM_TIMING_xxxx_yyyyxzzzz_nnn[i|p|PsF]

where:

xxxx 

Total number of lines.

yyyy x zzzz 

Width by height of the active video region (high definition).

nnn[i|p|PsF] 

The frame rate, followed by i, p, or PsF to indicate interlaced, progressive, or segmented Frame, respectively.

Standard Definition (SD) Timings

DM_TIMING_525 (NTSC)
DM_TIMING_625 (PAL)
High Definition (HD) Timings

DM_TIMING_1125_1920x1080_60p
DM_TIMING_1125_1920x1080_5994p
DM_TIMING_1125_1920x1080_50p
DM_TIMING_1125_1920x1080_60i
DM_TIMING_1125_1920x1080_5994i
DM_TIMING_1125_1920x1080_50i
DM_TIMING_1125_1920x1080_30p
DM_TIMING_1125_1920x1080_2997p
DM_TIMING_1125_1920x1080_25p
DM_TIMING_1125_1920x1080_24p
DM_TIMING_1125_1920x1080_2398p
DM_TIMING_1125_1920x1080_24PsF
DM_TIMING_1125_1920x1080_2398PsF
DM_TIMING_1125_1920x1080_30PsF
DM_TIMING_1125_1920x1080_2997PsF
DM_TIMING_1125_1920x1080_25PsF
DM_TIMING_1250_1920x1080_50p
DM_TIMING_1250_1920x1080_50i
DM_TIMING_1125_1920x1035_60i
DM_TIMING_1125_1920x1035_5994i
DM_TIMING_750_1280x720_60p
DM_TIMING_750_1280x720_5994p

DM_VIDEO_COLORSPACE_INT32

Sets the colorspace at the video jack. For input paths, this is the colorspace you expect to receive at the jack. For output paths, it is the colorspace you desire at the jack.

See “DM_IMAGE_COLORSPACE_INT32” in Chapter 7 for a detailed description of colorspace values.

Supported Colorspace Values

DM_COLORSPACE_RGB_601_FULL
DM_COLORSPACE_RGB_601_HEAD
DM_COLORSPACE_CbYCr_601_FULL
DM_COLORSPACE_CbYCr_601_HEAD
DM_COLORSPACE_RGB_240M_FULL
DM_COLORSPACE_RGB_240M_HEAD
DM_COLORSPACE_CbYCr_240M_FULL
DM_COLORSPACE_CbYCr_240M_HEAD
DM_COLORSPACE_RGB_709_FULL
DM_COLORSPACE_RGB_709_HEAD
DM_COLORSPACE_CbYCr_709_FULL
DM_COLORSPACE_CbYCr_709_HEAD

DM_VIDEO_SAMPLING_INT32

Sets the sampling at the video jack. (See “DM_IMAGE_SAMPLING_INT32” in Chapter 7 for a detailed description of sampling values.)

Supported Sampling Values

DM_SAMPLING_422
DM_SAMPLING_4224
DM_SAMPLING_444
DM_SAMPLING_4444

DM_VIDEO_PRECISION_INT32

Sets the precision (number of bits of resolution) in the signal at the jack. This is an integer. A precision value of 10, indicates a 10-bit signal. A value of 8 indicates an 8-bit signal.

DM_VIDEO_GENLOCK_SIGNAL_PRESENT_INT32

Used to query the incoming genlock signal for an output path. Not all devices may be able to sense genlock timing, but those that do will support this parameter. Common values match those for DM_VIDEO_TIMING, with two additions: DM_TIMING_NONE (there is no signal present) and DM_TIMING_UNKNOWN (the timing of the genlock cannot be determined).

DM_VIDEO_SIGNAL_PRESENT_INT32

Used to query the incoming signal on an input path. Not all devices may be able to sense timing, but those that do will support this parameter. Common values match those for DM_VIDEO_TIMING, with two additions: DM_TIMING_NONE (there is no signal present) and DM_TIMING_UNKNOWN (the timing of the input signal cannot be determined).

DM_VIDEO_GENLOCK_SOURCE_TIMING_INT32

Describes the genlock source timing. Only accepted on output paths. Each genlock source is specified as an output timing on the path and corresponds to the same timings as available with DM_VIDEO_TIMING_INT32.

DM_VIDEO_GENLOCK_TYPE_INT32

Describes the genlock signal type. Only accepted on output paths. Each genlock type is specified as either a 32-bit resource Id or DM_VIDEO_GENLOCK_TYPE_INTERNAL.

DM_VIDEO_BRIGHTNESS_INT32

Set or get the video signal brightness.

DM_VIDEO_CONTRAST_INT32

Set or get the video signal contrast.

DM_VIDEO_HUE_INT32

Set or get the video signal HUE.

DM_VIDEO_SATURATION_INT32

Set or get the video signal color saturation.

DM_VIDEO_RED_SETUP_INT32

Set or get video signal RED channel setup.

DM_VIDEO_GREEN_SETUP_INT32

Set or get the video signal GREEN channel setup.

DM_VIDEO_BLUE_SETUP_INT32

Set or get the video signal BLUE channel setup.

DM_VIDEO_ALPHA_SETUP_INT32

Set or get the video signal ALPHA channel setup.

DM_VIDEO_H_PHASE_INT32

Set or get the video signal horizontal phase genlock offset.

DM_VIDEO_V_PHASE_INT32

Set or get the video signal vertical phase genlock offset.

DM_VIDEO_FLICKER_FILTER_INT32

Set or get the video signal filter.

DM_VIDEO_DITHER_FILTER_INT32

Set or get the video signal dither filter.

DM_VIDEO_NOTCH_FILTER_INT32

Set or get the video signal notch filter.

DM_VIDEO_INPUT_DEFAULT_SIGNAL_INT64

Set or get the video signal default input signal.

DM_VIDEO_OUTPUT_DEFAULT_SIGNAL_INT64

Sets the default signal at the video jack when there is no active output. The only allowable are:

DM_SIGNAL_NOTHING indicates that output signal shall cease without generation of sync.
DM_SIGNAL_BLACK indicates that output shall generate a black picture complete with legal sync values.
DM_SIGNAL_COLORBARS indicates that output should use an internal colorbar generator.
DM_SIGNAL_INPUT_VIDEO indicates that output should use the default input signal as a pass through.

DM_VIDEO_START_Y_F1_INT32

Sets the start vertical location on F1 fields of the video signal. For progressive signals it specifies the start of every frame.

DM_VIDEO_OUTPUT_REPEAT_INT32

If the application is doing output and fails to provide buffers fast enough (the queue to the device underflows), then this control determines the device behavior. Allowable options are:

DM_VIDEO_REPEAT_NONE

The device does nothing, usually resulting in black output.

DM_VIDEO_REPEAT_FIELD

The device repeats the last field. For progressive signals or interleaved formats, this is the same as DM_VIDEO_REPEAT_FRAME.

DM_VIDEO_REPEAT_FRAME

The device repeats the last two fields. This output capability is device dependent and the allowable settings should be queried via the get capabilities of the DM_VIDEO_OUTPUT_REPEAT_INT32 parameter.

DM_VIDEO_FILL_Cr_REAL32

The Cr value for any pixel outside the clipping region. This is a real number: a value of 0.0 is the minimum legal value, 1.0 is the maximum legal value. Default is 0.

DM_VIDEO_FILL_Cb_REAL32

The Cb value for any pixel outside the clipping region. This is a real number: a value of 0.0 is the minimum legal value, 1.0 is the maximum legal value. Default is 0.

DM_VIDEO_FILL_RED_REAL32

The red value for any pixel outside the clipping region. This is a real number: a value of 0.0 is the minimum legal value (black), 1.0 is the maximum legal value. Default is 0.

DM_VIDEO_FILL_GREEN_REAL32

The green value for any pixel outside the clipping region. This is a real number: a value of 0.0 is the minimum legal value, 1.0 is the maximum legal value. Default is 0.

DM_VIDEO_FILL_BLUE_REAL32

The blue value for any pixel outside the clipping region. This is a real number: a value of 0.0 is the minimum (fully transparent), 1.0 is the maximum (fully opaque). Default is 1.0.

DM_VIDEO_START_X_INT32

Sets the start horizontal location on each line of the video signal.

DM_VIDEO_START_Y_F2_INT32

Sets the start vertical location on F2 fields of the video signal. Ignored for progressive timing signals.

DM_VIDEO_WIDTH_INT32

Sets the horizontal width of the clipping region on each line of the video signal.

DM_VIDEO_HEIGHT_F1_INT32

Sets the vertical height for each F1 field of the video signal. For progressive signals it specifies the height of every frame.

DM_VIDEO_HEIGHT_F2_INT32

Sets the vertical height for each F2 field of the video signal. For progressive signals, it always has value 0.

DM_VIDEO_FILL_Y_REAL32

The luminance value for any pixel outside the clipping region. This is a real number: a value of 0.0 is the minimum legal value (black), 1.0 is the maximum legal value. Default is 0.

DM_VIDEO_FILL_A_REAL32

The alpha value for any pixel outside the clipping region. This is a real number: a value of 0.0 is the minimum (fully transparent), 1.0 is the maximum (fully opaque). Default is 1.0.

Examples

Here is an example that sets the video timing and colorspace for an HDTV signal:

DMpv message[3]
message[0].param = DM_VIDEO_TIMING_INT32
message[0].value.int32 = DM_TIMING_1125_1920x1080_5994;
message[1].param = DM_VIDEO_COLORSPACE_INT32;
message[1].value.int32 = DM_COLORSPACE_CbYCr_709_HEAD;
message[2].param = DM_END;
dmSetControls( device, message);