The UMSImagePlayer class is an Ultimedia Services Version 2 feature and does not apply to Ultimedia Services Version 1.2.1.
The UMSImagePlayer class provides an abstract interface for displaying image files. Concrete implementations of the UMSImagePlayer class, such as the UMSLowLevelImagePlayer, use a UMSImageReader and one or more UMSImageWindow objects to read and display images from an image file. Extending a UMSImagePlayer's ability to display different kinds of image files only requires deriving new image reader objects from the base UMSImageReader class and adding the appropriate stanzas to the UMS configuration file.
The UMSImagePlayer is derived from the UMSObject.
To learn more about the UMSImagePlayer object, see:
For introductory information, see Media Handler Objects.
The enumerated lists that are defined for this object are:
enum Transform {
ROTATE_0,
ROTATE_90,
ROTATE_180,
ROTATE_270,
MIRROR_0,
MIRROR_90,
MIRROR_180,
MIRROR_270
};
enum ReturnCode {
Success,
Failure,
OutOfRange,
InvalidState,
UnsupportedVisual,
ValueChanged,
ReadFailed,
NoFile,
WrongFormat,
FileError,
NoWindow,
NoDisplay,
NoEvent,
CanNotConnect,
CommoFailure,
ForkFailed,
ExecFailed,
NoConnection,
NoLowLevelPlayer,
emoryAllocationFailure,
NullPointer
};
enum ColorUsage {
UseMinColors,
UseAllColors
};
typedef enum {
SOURCE_COORDINATE_SYSTEM /*the coordinate system of the image on disk*/
DESTINATION_COORDINATE_SYSTEM /*the coordinate system of a displayed image*/
} UMSImageCoordinateSystem;
typedef enum {
ROTATE_0, /*0 deg. rot. in x-y plane*/
ROTATE_90, /*90 deg. rot. in x-y plane*/
ROTATE_180, /*180 deg. rot. in x-y plane*/
ROTATE_270, /*270 deg. rot. in x-y plane*/
MIRROR_0, /*left to right mirror with 0 deg.rotation*/
MIRROR_90, /*left to right mirror with 90 deg. rotation*/
MIRROR_180, /*left to right mirror with 180 deg. rotation*/
MIRROR_270 /*left to right mirror with 270 deg. rotation*/
} UMSImageTransform;
The following constants define the list of possible UMSImagePlayer states:
const unsigned long NotReadyState = 0x00000001; const unsigned long ReadyState = 0x00000002; const unsigned long ReadingState = 0x00000004; const unsigned long DisplayingState = 0x00000008;
The following constants define the list of UMSImagePlayer events:
const unsigned long StateEvent = 0x00000001; const unsigned long ReadingEvent = 0x00000002; const unsigned long DisplayCompleteEvent = 0x00000004; const unsigned long ErrorEvent = 0xF0000000;
The following constants define true and false values used in the UMSImagePlayer's interface:
const boolean False = 0; const boolean True = 1;
The UMSImagePlayer class uses the UMSImageRect, UMSImageSize, and UMSImageColorProperties structures.
The UMSImageRect type defines a rectangular portion of an image in units of pixels. The origin (0,0) of an image is defined to be the top-left corner of the image.
typedef struct {
short top;
short left;
short bottom;
short right
}UMSImageRect;
The UMSImageSize type defines the size of an image in units of pixels
typedef struct {
long width;
long height;
}UMSImageSize;
The UMSImageColorProperties type defines values to control the red, green, and blue color balance, overall image lightness, and color saturation of an image. Positive values for the red, green, or blue color properties increase the amount of the corresponding color in the image. Increasing the lightness setting simultaneously increases the red, green, and blue values to increase the overall lightness of the image. Positive saturation values increase the saturation of the colors in the image, while leaving neutrals unaffected. Specifying negative values produces the opposite effect.
typedef struct {
short red;
short green;
short blue;
short lightness;
short saturation
}UMSImageColorProperties;
The UMSImagePlayer also defines the following structures:
The EventData structure defines the format of a UMSImagePlayer event. Since SOM's IDL doesn't support nested structures or unions, this data structure is flat:
typedef struct {
unsigned long event_type;
unsigned long state;
unsigned long image_index;
unsigned long percent;
ReturnCode error
}EventData;
The UMSImagePlayer state-transition diagram shows the effect of each UMSImagePlayer operation on the state of a UMSImagePlayer. The diagram also shows the state of the UMSImagePlayer required for an operation to succeed. For more information. see the UMSImagePlayer State Transition figure.
Any time a UMSImagePlayer changes state, it generates a StateEvent indicating the UMSImagePlayer's new state.
As shown in the figure, a UMSImagePlayer has the following states:
Each section below specifies the UMSImagePlayer's logical attributes and corresponding operations. A logical attribute is an attribute of an object that can or cannot be implemented as a member variable in the object's implementation (that is why it is called logical) yet is an attribute of the object.
Returns the state of a UMSImagePlayer. A UMSImagePlayer can be in one of four states; ReadyState, NotReadyState, ReadingState, or DisplayingState as defined in "Defined Constants" .
The return value of the get_state() method contains the current state of the UMSImagePlayer as defined in "Defined Constants" .
The get_file_info() method returns the pathname of a UMSImagePlayer's open image file and any string information associated with that file. The actual string information is image file specific and can include such information as copyright notices or the author's name.
Returns the number of images in the UMSImagePlayer's open image file.
| out long count | The number of images in the UMSImagePlayer's open image file. |
Sets the UMSImagePlayer's current image attribute to the image specified by the zero-based image_index parameter. Attempts to set the index to an invalid value (greater than or equal to the number of images) result in an error, in which case the current image remains unchanged. By default, the current image index is zero (0).
Returns the UMSImagePlayer's current image index. By default, the current image index is zero (0).
| in unsigned long image_num | The zero-based index of the UMSImagePlayer's current image. |
Use the set_image_caching() method to set a UMSImagePlayer's image caching attribute. When the image caching attribute is set to TRUE, a UMSImagePlayer caches image data instead of rereading the data each time the image is redisplayed. When set to FALSE, a UMSImagePlayer does not cache image data but instead rereads any image data required to redisplay an image. Set the image caching attribute to FALSE to preserve memory and to TRUE to obtain the best image update performance. By default, a UMSImagePlayer's image caching attribute is TRUE.
| in boolean image_caching_on | Use the image_caching_on parameter turn on (TRUE) or off (FALSE) image caching. |
Use the get_image_caching() method to query a UMSImagePlayer's image caching attribute. When the image caching attribute is set to TRUE, a UMSImagePlayer caches image data instead of rereading the data each time the image is redisplayed. When set to FALSE, a UMSImagePlayer does not cache image data but instead rereads any image data required to redisplay an image. Set the image caching attribute to FALSE to preserve memory and to TRUE to obtain the best image update performance. By default, a UMSImagePlayer's image caching attribute is TRUE.
Returns a UMSImagePlayer's filetype attribute which defines the type of a UMSImagePlayer's open image file. The string returned by the get_file_type() method is the file's type alias as defined in the UMS configuration file.
Your application is responsible for freeing the memory associated with the string.
| out string file_type | The filetype alias associated with the UMSImagePlayer's image file. |
Sets the UMSImagePlayer's display attribute. By default, the display attribute equals the value of the DISPLAY environment variable. Your application must set the display attribute to a valid value before calling the set_window(), set_colormap(), or set_colormap_id() methods.
If you change the display attribute, the UMSImagePlayer releases all of the windows associated with the UMSImagePlayer's images; therefore, you must reset the UMSImagePlayer's windows (via the set_window() method) and colormaps (via the set_colormap() or set_colormap_id() methods) after calling the set_display() method. All windows associated with a UMSImagePlayer's images (subsequently set via the set_window() method) must be owned by the UMSImagePlayer's display.
Returns the value of the UMSImagePlayer's display attribute in the form of an X display name. By default, a UMSImagePlayer's display attribute equals the value of the DISPLAY environment variable. To set the display attribute, use the set_display() method.
| out string display_name | The UMSImagePlayer's display name. Your application is responsible for freeing the display_name string. |
See the set_display() method for the format of the display_name parameter.
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
Sets a UMSImagePlayer's event mask attribute which enables or disables reporting of maskable events.
| in unsigned long event_mask | An OR set of bit flags enabling the corresponding events. The set of UMSImagePlayer event types is defined in "Defined Constants" . |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
Returns a UMSImagePlayer's event mask attribute which enables or disables reporting of maskable events. To set the mask, use the set_event_mask() method.
The get_event_mask() method returns an OR set of bits indicating which events are enabled. The set of UMSImagePlayer events is defined in "Defined Constants" .
This method checks a UMSImagePlayer's event queue for a Pending Event. If an event is pending, the method returns a nonzero value (true); otherwise it returns zero (false).
| Nonzero | If an event is pending. |
| Zero | If no events are pending. |
Returns a UMSImagePlayer's pending event in the space provided by event_data.
If no event is pending and the UMSImagePlayer is in the ReadingState, get_event() blocks until an event is received; for all other states, the get_event() method returns the NoEvent return code if no event is pending.
| out EventData event_data | Upon success, the event_data parameter contains the UMSImagePlayer's pending event. The EventData structure is defined in "Defined Constants" . |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| NoEvent | No event is pending. |
Returns an event handle which your application can use as a file descriptor on which to select, and thereby query or block on, UMSImagePlayer events.
The method returns a nonzero handle number for success and zero (0) for failure.
Note: A UMSImagePlayer maintains each of the attribute defined below for each of a UMSImagePlayer's images. For example, each of the UMSImagePlayer's images have a subimage rectangle attribute. The UMSImagePlayer's current image attribute is used to address a particular image in order to query or set the image's attributes. So to set the subimage rectangle attribute of a particular image, you first address the image by setting the UMSImagePlayer's current image attribute, via a call to set_image(), and then call the set_subimage() method to set the subimage attribute of the current image. Like all of the methods in this section, the set_subimage() method does not affect the subimage rectangle attribute of the UMSImagePlayer's other images. If you're using a UMSImagePlayer to display images from image files containing only one image, you need not set the UMSImagePlayer's current image attribute since the attribute defaults to the first (and only) image in an image file.
Use the get_image_info() method to query information (if any) associated with a UMSImagePlayer's current image.
Copyright-specific information is returned by the get_copyright_info() method. Information associated with the UMSImagePlayer's open image file is returned by the get_file_info() method. For some image files, the information returned by get_image_info() can be identical to the information returned by get_file_info() and both methods can also contain copyright information.
| Success | No error was found. |
| Failure | An error was detected that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Use the get_copyright_info() method to query the copyright information (if any) associated with a UMSImagePlayer's current image.
| Success | No error was found. |
| Failure | An error was detected that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Use the supports_arbitrary_scaling() method to determine if a UMSImagePlayer's supports arbitrary scaling for the current image. For more information on image scaling, see "Current Image's Sizes, Size, and Display Size" .
Use the supports_color_properties() method to determine if a UMSImagePlayer's supports setting the current image's color properties.
Use the get_transforms() method to query the current images list of supported image transformations. The values returned are used to set the current image's transform attribute via the set_transform() method. For more information on image transformations, see "Current Image's Transform" .
| Success | No error was found. |
| Failure | An error was detected that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Sets the current image's subimage rectangle attribute which defines the portion of the current image the UMSImagePlayer object displays. To display the entire image (the default), set the rect parameter to NULL.
You have a choice of coordinate systems when specifying the current image's subimage rectangle. You can specify the rectangle in either the source or destination coordinate systems by using the coord_system parameter whose value can either be SOURCE_COORDINATE_SYSTEM or DESTINATION_COORDINATE_SYSTEM. The source coordinate system is the coordinate system of the image as stored in the image file. The origin of the source coordinate system is the upper-left corner of the image and the coordinate system's extent is defined by the current image's size attribute which you can set and query using the set_image_size() and get_image_size() methods, respectively. The source coordinate system does not reflect the current image's display size or transformation attributes.
The destination coordinate system is the coordinate system the UMSImagePlayer uses when displaying the current image. The destination coordinate system is defined by the current image's display Size attribute which your application can set and query using the set_display_size() and get_display_size() methods. The destination coordinate system's origin is the upper left corner of the image after application of all transformations such as rotations.
An error is returned if any of the coordinates of the specified subimage rectangle are outside the bounds of the specified coordinate system or if the rectangle is degenerate in any way (For example, if the rectangle's top coordinate is more than its bottom coordinate, or its right coordinate is less than its left coordinate.). If any error is detected, the current image's subimage rectangle remains unchanged.
If you specify the current image's subimage rectangle in the source coordinate system and then change the current image's size attribute, the current image's subimage rectangle is automatically mapped to the new image size. Likewise, if you specify the current image's subimage rectangle in the destination (display) coordinate system and then change the current image's display Size attribute, the current image's subimage rectangle is automatically mapped to the new display size.
Note: Because of rounding errors, the mapping might not result in the display of exactly the same subimage both before and after the mapping.
| in UMSImageCoordinateSystem coord_system | The coord_system parameter specifies the coordinate system of the rectangle specified by the rect parameter. |
| in UMSImageRect* rect | Upon return from the set_transform() method, the actual_display_subimage_rect parameter contains the value of the current image's subimage rectangle attribute as defined in the display (destination) coordinate system.
A rectangle defining the current image's subimage rectangle. See "Defined Structures" for a definition of the UMSImageRect structure. |
| out UMSImageSize actual_display_size | Upon return from the set_subimage() method, the actual_display_size parameter contains the value of the current image's display size attribute which is the size (width and height) the UMSImagePlayer uses when displaying the current image. For more information on the current image's display size attribute, see "Current Image's Sizes, Size, and Display Size" . |
| out UMSImageRect actual_display_subimage_rect | Upon return from the set_transform() method, the actual_display_subimage_rect parameter contains the value of the current image's subimage rectangle attribute as defined in the display (destination) coordinate system. |
Returns the value of the current image's subimage rectangle attribute. The coordinates returned are defined in the coordinate system specified by the coord_system parameter. For more information on image coordinate systems and subimage rectangles, see the description of the set_subimage() method .
| in UMSImageCoordinateSystem coord_system | Use the coord_system parameter to specify the coordinate system of the rectangle returned by the rect parameter. See "Enumeration Lists" for a definition of the UMSImageCoordinateSystem enumeration. |
| out UMSImageRect rect | The subimage rectangle the UMSImagePlayer object uses when displaying the current image. |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Use the get_subimage_coordinates() method to query the coordinates of a subimage rectangle in either the current image's source (image) coordinate system or the current image's destination (display) coordinate system given the coordinates of a subimage rectangle in the other coordinate system.
| in UMSImageCoordinateSystem coord_system | Use the coord_system parameter to specify either the source or destination coordinate system of the input rectangle (input_rect). The value of the coord_system parameter can be either SOURCE_COORDINATE_SYSTEM, referring to the coordinate system of the image as read from the image file, or the DESTINATION_COORDINATE_SYSTEM, referring to the coordinate system in which the image is displayed. Whichever coordinate system you choose for the input_rect parameter, the method returns output_rect parameter defined in the other coordinate system. For example, if you define the input_rect in the SOURCE_COORDINATE_SYSTEM, the method returns the output_rect parameter relative to the DESTINATION_COORDINATE_SYSTEM. See "Enumeration Lists" for a definition of the UMSImageCoordinateSystem enumeration. |
| in UMSImageRect input_rect | Use the input_rect parameter to specify subimage rectangle in the coordinate system specified by the coord_system parameter. The get_subimage_coordinates() method calculates the output_rect from the specified input_rect using the ratio of the current image's size and current image's display size attributes. |
| out UMSImageRect output_rect | Upon a successful return from the get_subimage_coordinates() method, the output_rect parameter contains the coordinates of the specified input_rect mapped to either the source or destination coordinate systems depending upon the value of the coord_system parameter. For example, if you specify a coordinate system of SOURCE_COORDINATE_SYSTEM via the coord_system parameter, the coordinates of the output_rect parameter are returned in the DESTINATION_COORDINATE_SYSTEM, and vice-versa. |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
The set_window() method associates the specified window with the current image. If the format of the current image and the X visual of the specified window are incompatible, the method returns the UnsupportedVisual return code. If you've already set the current image's window attribute, the set_window() method implicitly calls the release_window() method before setting the new window.
Before calling the set_window() method, a UMSImagePlayer's display attribute must be set to a valid value. See the set_display() method for more information.
If set_window() is called while the UMSImagePlayer is in the ReadingState or DisplayingState, the current image is read from the UMSImagePlayer's image file and displayed in the specified window. Reading the image from the image file can cause the UMSImagePlayer to move to the ReadingState. If you call set_window() while the UMSImagePlayer is in the ReadyState, the current image is read and displayed the next time your application calls the start_display() method.
| in unsigned long window | Specifies the X window ID to associate with the current image. |
Returns the X window ID associated with the UMSImagePlayer's current image. If no window is associated with the current image, the get_window() method returns the NoWindow return code and the output parameter is undefined.
| out unsigned long window_id | The X window ID associate with the current image. |
Releases the X window associated with the current image. If the UMSImagePlayer is in the ReadingState or DisplayingState, a call to release_window() causes the UMSImagePlayer to stop actively displaying the current image. If the current image is already displayed, a UMSImagePlayer does not remove the image but stops handling the image's window-system expose events.
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Use the get_image_sizes() method to obtain the list of native image sizes (resolutions) available for the current image. Each size specifies an image width and height in units of pixels.
Through the set_image_size() method, you can set the current image's size attribute to any one of the image sizes returned by the get_image_sizes() method.
| out sequence<UMSImageSize> sizes | Upon a successful return from the get_image_sizes() method, the sizes parameter contains a sequence of UMSImageSize structures, each of which define one of the native image sizes, or resolutions, available for the current image.
The UMSImageSize type is defined in "Defined Structures" . Your application is responsible for freeing the memory address by sizes._buffer. |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Use the set_image_size() method to select one of the native image sizes (resolutions) available for the UMSImagePlayer's current image. The list of native image sizes is returned by the get_image_sizes() method. You must specify one of the image sizes returned by the get_image_sizes() method; otherwise the set_image_size() method returns the OutOfRange return code.
The actual size of the current image when displayed by a UMSImagePlayer is controlled by the current image's display size attribute which is set and queried using the set_display_size() and get_display_size() methods irrespectively. If the UMSImagePlayer does not support scaling between the specified image_size and the current image's display size, the set_image_size() method modifies the current image's display size and returns the new display size in the actual_display_size parameter. The method also returns the ValueChanged return code. To change both the current image's image size and current image's display size via one method call, use the set_image_and_display_sizes() method. See "Current Image's Sizes, Size, and Display Size" for more information regarding the interaction between the current image's size and the current image's display size attributes.
| in UMSImageSize* image_size | Use the image_size parameter to specify the desired image size for the current image. You can use the get_image_sizes() method to get the list of image sizes available for the current image. If you specify an image size not returned by get_image_sizes(), the set_image_size() method returns the OutOfRange return code.
The UMSImageSize type is defined in "Defined Structures" . |
| out UMSImageSize actual_display_size | The actual_display_size parameter contains the actual display size the UMSImagePlayer uses when displaying the current image. If the actual display size differs from the current image's display size in affect before you called the set_image_size() method, the set_image_size() method returns the ValueChanged return code. |
| out UMSImageRect actual_display_subimage_rect | The actual_display_subimage_rect parameter contains the coordinates (top, left, bottom, right) of the current image's subimage rectangle defined in the destination (display) coordinate system. If, as a result of calling the set_image_size() method, the UMSImagePlayer changes the current image's subimage rectangle attribute, the set_image_size() method returns the ValueChanged return code.
The UMSImageRect type is defined in "Defined Structures" . |
Use the get_image_size() method to query the current image's size attribute which defines which of the current image's sizes the UMSImagePlayer uses when displaying the current image.
You can use the get_image_sizes() method to query the current image's list of available image sizes and the set_image_size() method to select one of the available image sizes. Use the set_display_size() and get_display_size() methods to set and query the current image's display size attribute which, if the UMSImagePlayer supports scaling, can differ from the current image's size.
| out UMSImageSize size | The current image's size in units of number of pixels. The UMSImageSize type is defined in "Defined Structures" . The size (Specifically, width and height) is in units of number of pixels. |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Sets the current image's display size attribute which defines the height and width (in units of pixels) of the current image when displayed by a UMSImagePlayer.
Depending on an image's format, the UMSImagePlayer cannot support arbitrary scaling of an image's data. If scaling is supported, you can set the current image's display size to any positive height and width values and the UMSImagePlayer scales the current image, from the current image's size to the specified display size.
When the UMSImagePlayer does not support arbitrary scaling for a particular image format, the following restrictions apply to the current image's display size attribute and to the display_size argument of the set_display_size() method:
Use the get_display_size() method to query the current image's display size attribute and the get_image_sizes(), set_image_size(), get_image_size() methods to query the current image's sizes, set the current image's size, and query the current image's size, respectively.
| in UMSImageSize* display_size | Use the display_size parameter to specify the desired display size (width and height) for the current image. The UMSImageSize type is defined in "Defined Structures" . The specified height and width must be positive values; otherwise the method returns the OutOfRange return code. |
| out UMSImageSize actual_display_size | The actual_display_size parameter contains the actual display size the UMSImagePlayer uses when displaying the current image. If the actual display size differs from the display size you specify via the size parameter, the set_display_size() method returns the ValueChanged return code. |
| out UMSImageRect actual_display_subimage_rect | The actual_display_subimage_rect parameter contains the coordinates (top, left, bottom, right) of the current image's subimage rectangle defined in the destination (display) coordinate system. If, as a result of calling the set_display_size() method, the UMSImagePlayer changes the current image's subimage rectangle attribute, the set_display_size() method returns the ValueChanged return code.
The UMSImageRect type is defined in "Defined Structures" . |
Returns the current image's display size attribute (Specifically, width and height) in units of number of pixels. The current image's display size attribute is set via the set_display_size() method.
| out UMSImageSize size | After a successful call to the get_display_size() method, the size parameter contains the current image's display size in units of number of pixels.
The UMSImageSize type is defined in "Defined Structures" . |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
As an alternative to using the set_image_size() and set_display_size() methods, you can use the set_image_and_display_sizes() method to simultaneiously set the current image's image size and display size attributes.
The image size you specify must be one of the native image sizes is returned by the get_image_sizes() method; otherwise the set_image_size() method returns the OutOfRange return code.
The actual size of the current image when displayed by a UMSImagePlayer is controlled by the current image's display size attribute which is set via the display_size parameter. If the UMSImagePlayer does not support scaling between the specified image_size and display_size, the set_image_and_display_sizes() method returns the actual display size in the actual_display_size parameter and returns the ValueChanged return code.
When the UMSImagePlayer does not support arbitrary scaling for a particular image format, the following restrictions apply to the current image's display size attribute and to the display_size argument of the set_display_size() method:
Use the get_display_size() method to query the current image's display size attribute. See "Current Image's Sizes, Size, and Display Size" for more information regarding the interaction between the current image's size and the current image's display size attributes.
| in UMSImageSize* image_size | Use the image_size parameter to specify the desired image size for the current image. You can use the get_image_sizes() method to get the list of image sizes available for the current image. If you specify an image size not returned by get_image_sizes(), the set_image_size() method returns the OutOfRange return code.
The UMSImageSize type is defined in "Defined Structures" . |
| in UMSImageSize* display_size | Use the display_size parameter to specify the desired display size (width and height) of the current image. |
| out UMSImageSize actual_display_size | The actual_display_size parameter contains the actual display size the UMSImagePlayer uses when displaying the current image. If the actaul_display_size differs from the specified display_size, the set_image_and_display_sizes() method returns the ValueChanged return code. |
| out UMSImageRect actual_display_subimage_rect | The actual_display_subimage_rect parameter contains the coordinates (top, left, bottom, right) of the current image's subimage rectangle defined in the destination (display) coordinate system. If, as a result of calling the set_image_and_display_sizes() method, the UMSImagePlayer changes the current image's subimage rectangle attribute, the set_image_and_display_sizes() method returns the ValueChanged return code.
The UMSImageRect type is defined in "Defined Structures" . |
Sets the current image's base colormap index (zero-based) and size (number of colormap entries). If the requested colormap base index or size is not supported, the method returns ValueChanged with the respective output parameters reflecting values which are supported.
If the UMSImagePlayer is in the ReadingState or DisplayingState, the actual colormap size and base-index values are immediately applied to the current image. If the UMSImagePlayer is in the ReadyState, the actual colormap size and base-index values are applied when your application next calls the start_display() method.
Returns the base index (zero based) and size (number of colormap entries) of the current image's colormap.
| out unsigned long base_index | The base index (zero based) of the current image's colormap. |
| out unsigned long size | The size (number of colormap entries) in the current image's colormap. |
Sets the colormap associated with the UMSImagePlayer's current image. The current image's colormap attributes, set using the set_colormap_attributes() method, define the colormap's base index (zero based) and size.
The set_colormap() method has the effects of:
If the colormap you specify is not supported by the current image, the set_colormap() method returns the ValueChanged return code and sets actual_colormap._buffer to point to a copy of the actual colormap the UMSImagePlayer uses when displaying the current image. The set_colormap() method also sets the actual_colormap._length and actual_colormap._maximum fields to reflect the size of the actual colormap pointed to by actual_colormap._buffer. So, when the set_colormap() method returns ValueChanged, your application is responsible for freeing the memory pointed to by actual_colormap._buffer. If the set_colormap() method returns something other than ValueChanged (for example, Success, Failure, or InvalidState), the actual_colormap._buffer is not set; therefore, your application should not free the actual_colormap._buffer.
Each colormap entry is four bytes long and is encoded as pad, red, green, and blue as shown in the following figure.
If the UMSImagePlayer is in the ReadingState or DisplayingState, the actual colormap is immediately applied to the current image. If the UMSImagePlayer is in the ReadyState, the actual colormap is applied when your application next calls the start_display() method.
| in sequence<octet> colormap | The colormap parameter contains the colormap, defined as a sequence of octets (8 bit bytes), you would like the UMSImagePlayer to use when displaying the current image. The colormap._length field should contain the number of octets in the colormap where each colormap entry is four octets (bytes) long and is encoded as pad, red, green, and blue. |
| out sequence<octet> actual_colormap | If the set_colormap() method returns the ValueChanged return code, the actual_colormap._buffer contains the actual colormap the UMSImagePlayer uses when displaying the current image; in which case your application is responsible for freeing the actual_colormap._buffer. The actual_colormap._length and actual_colormap._maximum fields contain the length of the actual colormap in units of octets (bytes). Each colormap entry is four octets (bytes) long and is encoded as pad, red, green, and blue as shown in the figure .
If the set_colormap() method returns Success, Failure, or InvalidState, the actual_colormap._buffer is not set and should not be freed by your application. |
Returns the colormap associated with the current image. The current image's colormap attributes, returned by the get_colormap_attributes() method, define the size and base index (zero based) of the current image's colormap. Your application is responsible for freeing the actual_colormap._buffer.
Each color map entry is four octets (bytes) long and is encoded as pad, red, green, and blue as shown in the figure .
Sets the current image's X colormap ID attribute. The specified colormap_id must refer to an X colormap resource created on the UMSImagePlayer's Display. If the specified X colormap ID represents a colormap not suitable for current image (for example, the current image does not allow the specification of a colormap), the actual_colormap_id parameter contains the actual X colormap ID the UMSImagePlayer uses when displaying the current image.
If the UMSImagePlayer is in the ReadingState or DisplayingState, the actual colormap ID is immediately applied to the current image. If the UMSImagePlayer is in the ReadyState, the actual colormap ID is applied when your application next calls the start_display() method.
Be default, all of a UMSImagePlayer's images have an X colormap ID attribute which you can query using the get_colormap_id() method.
Returns the current image's X colormap ID attribute the UMSImagePlayer uses when displaying the current image.
| out unsigned long colormap_id | The colormap_id parameter contains the X colormap ID the UMSImagePlayer uses when displaying the current image. |
Sets the current image's transform attribute. If the specified transform is not supported, the actual_transform parameter contains the actual image transformation the UMSImagePlayer uses when displaying the current image.
Use the get_rightsideup_transform() method to determine current image's default image transformation and use the get_transform() method to determine the current image's current transformation.
| in UMSImageTransform transform | Use the transform parameter to specify the image transform you would like the UMSImagePlayer to apply when displaying the current image.
The UMSImageTransform type is defined in "Enumeration Lists" . |
| out UMSImageSize actual_display_size | Upon return fro the set_transform() method, the actual_display_size parameter contains the value of the current image's display size attribute which is the size (width and height) the UMSImagePlayer uses when displaying the current image. For more information on the current image's display size attribute, see "Current Image's Sizes, Size, and Display Size" . |
| out UMSImageRect actual_display_subimage_rect | Upon return from the set_transform() method, the actual_display_subimage_rect parameter contains the value of the current image's subimage rectangle attribute as defined in the display (destination) coordinate system. For more information on the current image's subimage rectangle attribute, see "Current Image's Subimage Rectangle" . |
ReadyState, ReadingState, or DisplayingState
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Returns the current image's transform attribute which defines the image transformation the UMSImagePlayer uses when displaying the current image.
Use the set_transform() method to set the current image's transform attribute.
The UMSImageTransform type is defined in "Enumeration Lists" .
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Returns the current image's right-side-up transform attribute. You can use the returned value in the set_transform() method to rotate the current image into a right-side-up orientation. Some image formats do not support the concept of a right-side-up transformation. Therefore, images defined in those formats always have a right-side-up tansform of ROTATE_0 and may not appear to you to be right-side-up.
By default, the transform attribute of a UMSImagePlayer image is set to the image's right-side-up transform so that the image, by default, appears right-side-up. For more information on image transformations, see "Current Image's Transform" .
| out UMSImageTransform transform | After a successful call to the get_rightsideup_transform() method, the transform parameter contains one of the UMSImageTransform enumeration values indicating the transformation which must be applied to display the current image right-side-up. The UMSImageTransform enumeration is defined in "Enumeration Lists" . |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Returns the current image's associated Image Pathname attribute as a string. If the current image has no associated image pathname, the method returns a NULL.
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Sets the current image's color properties attribute which controls the red, green, and blue color balance, overall image lightness, and color saturation of the current image. Positive values for the red, green, or blue color properties increase the amount of the corresponding color in the Current Image. Increasing the lightness setting simultaneously increases the red, green, and blue values to increase the overall lightness of the Current Image. Positive saturation values increase the saturation of the colors in the image, while leaving neutrals unaffected. Specifying negative values produces the opposite effect.
| in UMSImageColorProperties image_color_properties | Use the image_color_properties argument to set the red, green, and blue color balance, overall image lightness, and color saturation of the current image. The UMSImageColorProperties structure is defined in "Defined Structures" . |
| out UMSImageColorProperties actual_image_color_properties | |
| Upon return from the set_color_properties() method, the actual_image_color_properties argument contains the actual image color properties of the current image. If the image color properties you specify in the image_color_properties argument differ from the actual image color properties returned in the actual_image_color_properties argument, the set_color_properties() method returns the ValueChanged return code. | |
Gets the current image's color properties attribute which controls the red, green, and blue color balance, overall image lightness, and color saturation of the current image. Positive values for the red, green, or blue color properties increase the amount of the corresponding color in the current image. Increasing the lightness setting simultaneously increases the red, green, and blue values to increase the overall lightness of the current image. Positive saturation values increase the saturation of the colors in the image, while leaving neutrals unaffected. Specifying negative values produces the opposite effect.
| out UMSImageColorProperties image_color_properties | Upon return from the get_color_properties() method, the image_color_properties argument contains the Image Color Properties of the current image. The UMSImageColorProperties structure is defined in "Defined Structures" . |
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
The following methods are operations which can be performed on a UMSImagePlayer.
Opens an UMSImagePlayer to play the image file specified by the pathname parameter. If the file cannot be played, an error is returned. After a successful call to open(), the state of a UMSImagePlayer is ReadyState. If the UMSImagePlayer is already in the ReadyState, the open() method first closes the file it has open (see the close() method) before opening the specified file. If the UMSImagePlayer is in the DisplayingState, the open() method first stops displaying images from the currently opened file (see the stop_display() method), then closes the currently open file (see the close() method), before actually opening the specified file.
| in string pathname | The pathname of the image file to open. |
The close() method closes the UMSImagePlayer freeing all allocated resources, releasing any windows associated with the UMSImagePlayer's images (see the set_window() and release_window() methods), and closing the image file opened by the open() method. After a successful call to the close() method, the state of a UMSImagePlayer is NotReadyState.
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
The start_display() method starts the process of displaying a UMSImagePlayer's images.
Part of the process is to read image data from the UMSImagePlayer's open image file. When starting the read, the UMSImagePlayer moves to the ReadingState and generates an IsReading event. After reading and displaying all of the image data, a UMSImagePlayer's state move to the DisplayingState and the UMSImagePlayer generates an IsDisplaying event.
While in the DisplayingState, a UMSImagePlayer maintains an image on the screen by redrawing all of part of the image whenever the image is exposed or the state of the image is modified by your application. For example, if a UMSImagePlayer is displaying the fifth image in an image file, and your application modifies the colormap of the fifth image, the UMSImagePlayer redisplays the fifth image using the new colormap.
In some cases, redisplaying all or part of an image can require the UMSImagePlayer to reread the image data from the image file. If so, the UMSImagePlayer's changes to the ReadingState and generates an IsReading event.
Note that only those images associated with an X window, through the set_window() method, are actually read and displayed by the start_display() method.
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
Stops the display and expose event handling of the all of the UMSImagePlayer's images.
After a successful call to the stop_display() method, the state of the UMSImagePlayer is the ReadyState.
| Success | No error was found. |
| Failure | If an error is found that is not described by any other return code. |
| InvalidState | The state of the UMSImagePlayer precludes calling this method. |
For introductory information, see Media Handler Objects.
