[ Previous | Next | Contents | Glossary | Home | Search ]
Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

UMSVideoIn Object

The UMSVideoIn object is an Ultimedia Services Version 2 feature and does not apply to Ultimedia Services Version 1.2.1.

The UMSVideoIn object is a base class and is not meant to be instantiated. This class provides an interface for a VideoIn and Monitor object. The device specific objects for VideoIn and monitor would be instantiated by a VideoIn metaclass. The VideoIn class would enable the capture of either compressed or uncompressed digital video, which would be suitable for a UMSCapture object or for an application such as video conferencing. A VideoIn object would also allow the monitoring of the captured video in a window. This could be all frames or only the captured frames. A VideoIn object is always a monitor, but the object could also be instantiated as a monitor in case monitoring is the only desired function. In the case where the hardware does not support monitoring, the monitoring would have to be accomplished outside of the VideoIn object.

This class inherits from the UMSNegotiatorSource and the UMSVideoMonitor class.

To learn more about the UMSVideoIn object, see:

For introductory information, see Video, Monitor, and Camera Control Support Objects.

Enumeration Lists

To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list can vary with the application. The method descriptions detail valid or possible values for the specific use. The enumerated lists that are defined for this object are listed below:

enum ReturnCode {
   Success,      method completes successfully
   Failure,      method failed
   NotOpen,      Device not open
   NotSupported,   method not implemented in chosen subclass
   SettingsChanged,   given setting changed. Check out param.
   InvalidArgument,   Passed an invalid argument to method.
   NullPointer,   An out parameter is NULL.
   DeviceNotFound,   Could not find given device
   DeviceNotAvail,   No ports available for video
   DeviceNotOpen,   Device not open.
   InvalidSubimageSize,  Tried to set an illegal subimage.
   InvalidImageSize,   Tried to set an illegal image size
   MonitorNotActive   Tried to change a monitor setting when monitor not turned                on.
   };

Method Descriptions

ReturnCode set_max_buffered_frames (in long frames, out long frames_returned)

Description

If the video device driver for the hardware supports it, this call allows the management of the video buffer. This would be to control latency for different types of applications. A video conference would need low latency and would allow for missed frames and the most recent frame. A capture application would not care about latency, but would need all of the frames, not just the most recent.

Arguments
in long frames Amount of frames to buffer. This is a request. The amount may not be supported.
out long frames_returned Amount of frames really in the buffer. This could be zero (0) if the device driver does not have a buffer.
Return Values

Success

Failure

ReturnCode get_max_buffered_frames (out long frames)

Description

This method returns the buffer size of the device buffer, if there is one. If the size was not set, this returns whatever the default for the hardware is.

Arguments
out long frames Size of the frame queue.
Return Values

Success

Failure

ReturnCode get_buffered_frame_count (out long frames)

Description

This method returns the number of frames that have been buffered. A positive, nonzero value is returned if the queue size is greater than zero and the input call has been issued.

Arguments
out long frames Number of frames in buffer.
Returns

Success

Failure

ReturnCode flush()

Description

This method discards all of the frames in the buffering queue.

Return Values

Success

Failure

ReturnCode input (in UMSVideoMonitor::OnOff flag)

Description

This method starts or stops the video capture. If there is a queue size defined, this call causes the queue to start to fill.

Arguments
in UMSVideoMonitor::OnOff flag Indicates whether to turn the input on or off
Return Values

Success

Failure

ReturnCode get_frame (out sequence<octet>buffer, out unsigned long time_stamp, out long missed_frames)

Description

This method returns one frame to the client. A time stamp for the frame is also returned along with the number of missed frames, if any.

Arguments
out sequence<octet>buffer Pointer to the buffer that holds one frame of data.
out unsigned long time_stamp Time stamp of frame
out long missed_frames Number of missed frames, if any.
Return Values

Success

Failure

ReturnCode set_time_format (in UMSVideoTypes::TimeFormat format)

Description

Set the time format to milliseconds, frames, or fields.

Arguments
in UMSVideoTypes::TimeFormat format Enumerated type for time format
Returns

Success

Failure

ReturnCode get_time_format (out UMSVideoTypes::TimeFormat format)

Description

Get the current time format.

Arguments
out UMSVideoTypes::TimeFormat format Enumerated type for time format
Return Values

Success

Failure

ReturnCode set_input_rate (in float rate, out float rate_returned)

Description

Set the frequency at which frames are placed in the queue, or at which frames are available if queue size is 0.

Arguments
in float rate Input frequency. Can have a fraction.
out float rate_returned The rate that device really uses if given rate unsupported.
Return Values

Success

Faliure

ReturnCode get_input_rate (out float rate)

Description

Get the current input frequency or default.

Arguments
out float rate The returned rate.
Return Values

Success

Failure

ReturnCode monitor_only_received (in UMSVideoMonitor::OnOff flag)

Description

Only monitor frames that are captured to memory. The default behavior is to monitor every frame.

Arguments
in UMSVideoMonitor::OnOff flag Enumerated type to set the behavior.
Return Values

Success

Faliure

ReturnCode set_image_size (in long width, in long height, out long width_returned, out long height_returned)

Description

Set the dimensions of the captured image size. If the size set is greater than the hardware image size, hardware scaling (or zoom) is attempted.

Arguments
in long width Desired width of captured image.
in long height Desired height of captured image.
out long width_returned Width that hardware can support.
out long height_returned Height that hardware can support.
Return Values

Success

Failure

ReturnCode get_input_image_size (out long width, out long height)

Description

Get the current image size if set, or return the default for a particular hardware type.

Arguments
out long width Current image width
out long height Current image height
Return Values

Success

Failure

For introductory information, see Video, Monitor, and Camera Control Support Objects.


[ Previous | Next | Contents | Glossary | Home | Search ]