Chapter 5. Audio/Video Jacks

ML is concerned with three types of interfaces:

All share common control, buffer, and queueing mechanisms. This chapter describes these mechanisms in the context of operating on a jack and its associated path. The OpenML Media Library Software Development Kit Programmer's Guide discusses the application of these mechanisms to transcoders and pipes.

Open a Jack

To open a connection to a jack, call mlOpen:

MLstatus mlOpen(const MLint64 objectId, MLpv* options, MLopenid* openId);

A jack is usually an external connection point and most often one end of a path. Jacks may be shared by many paths or they may have other exclusivity inherent in the hardware. For example, a common video decoder may have a multiplexed input shared between composite and S-video. If only one can be in use at a given instance, then there is an implied exclusiveness between them.

Many jacks do not support an input message queue because an application cannot send data to a jack (it must be sent via a path). Therefore, mlSendControls and mlSendBuffers are not supported on a jack; you must use mlSetControls to adjust controls. Typically, the adjustments on a path affect hardware registers and can be changed while a data transfer is ongoing (on a path that connects the jack to memory). Examples are brightness and contrast.

Some controls are not adjustable during a data transfer. For example, the timing of a jack cannot usually be changed while a data transfer is in effect. Reply messages may be sent by jacks and usually indicate some external condition, such as synchronization lost or gained.

Construct a Message

Messages are arrays of parameters, where the last parameter is always ML_END. For example, you can adjust the flicker and notch filters with a message such as the following:

MLpv message[3];
message[0].param = ML_VIDEO_FLICKER_FILTER_INT32;
message[0].value.int32 = 1;
message[1].param = ML_VIDEO_NOTCH_FILTER_INT32;
message[1].value.int32 = 1;
message[2].param = ML_END 

Set Jack Controls

Jack controls deal with external conditions and not processing associated with data transfers. Therefore, applications use mlSetControls or mlGetControls calls to manipulate these controls. Following is an example of how you can obtain the external synchronization signal (genlock) vertical and horizontal phase immediately:

MLpv message[3];
message[0].param = ML_VIDEO_H_PHASE_INT32;
message[1].param = ML_VIDEO_V_PHASE_INT32;
message[2].param = ML_END;
if( mlGetControls( aJackConnection, message)) 		handleError();
   printf("Horizontal offset is %d, Vertical offset is %d\n",
      message[0].value.int32, message[1].value.int32);

mlSetControls and mlGetControls are blocking calls. If the call succeeds, the message has been successfully processed.

Note: Not all controls may be set via mlSetControls. The access privilege in the param capabilities can be used to verify when and how controls can be modified.

Close a Jack

When an application has finished using a jack, it should close it with mlClose:

MLstatus mlClose(MLopenid openId);

All controls previously set by this application normally remain in effect although they may be modified by other applications.