The Image Player is an Ultimedia Services Version 2 feature and does not apply to the Ultimedia Services Version 1.2.1.
Each section below specifies the UMSImagePlayer's logical attributes. 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 that can be generized and sometimes set.
To learn more about the image player, see:
The UMSImagePlayer's state attribute defines the operating state of a UMSImagePlayer. A UMSImagePlayer can be in either the NotReadyState, ReadyState, ReadingState, or DisplayingState as shown in the following figure.
The state of a UMSImagePlayer is important because it limits the methods your application can call. For example, your application cannot call the set_current_image() method while a UMSImagePlayer is in the NotReadyState, because a UMSImagePlayer in the NotReadyState does not have an open image file and therefore does not have a current image.
The image file info attribute defines image file specific information. The actual content of the information is image-file specific but can contain information such as copyright notices, the or author's name.
The image file info attribute is only defined for UMSImagePlayer's in the ReadyState, ReadingState, or DisplayingState.
The image count attribute defines the number of images in a UMSImagePlayer's open image file. The image count attribute is only defined in the ReadyState, ReadingState, or DisplayingState.
A UMSImagePlayer's current image attribute defines the image on which other UMSImagePlayer methods operate. The current image attribute is only defined in the ReadyState, ReadingState, or DisplayingState.
The image caching attribute controls whether a UMSImagePlayer's caches image data read from an image file or rereads the data each time an image is displayed or exposed. When you set the image caching attribute to FALSE, the UMSImagePlayer does not cache image data but instead rereads the data when necessary. The advantage of setting the image caching attribute to FALSE is lower memory usage. The advantage of setting it to TRUE is faster response to image updates, such as when the image's window is exposed due to you moving windows around on the screen. By default a UMSImagePlayer's image caching attribute is TRUE.
You can modify or query a UMSImagePlayer's image caching attribute when a UMSImagePlayer is in any state.
The filetype attribute defines the type of a UMSImagePlayer's open image file and is defined as a string. The filetype attribute is only defined in the ReadyState, ReadingState, or DisplayingState.
A UMSImagePlayer's display attribute defines the X display connection a UMSImagePlayer uses when displaying images. By default, the display attribute is equal the value of the DISPLAY environment variable. If the DISPLAY variable is not set or is set to an invalid X display name, your application must call the UMSImagePlayer's set_display() method before associating images with windows or colormaps.
The display attribute can be set or queried when the UMSImagePlayer is in any state.
The event mask attribute defines which UMSImagePlayer events your application receives from a UMSImagePlayer. The event mask attribute is specified as an OR combination of the constants defined in "Defined Constants" . Each event is enabled when its corresponding bit in the event mask is set to 1. By default, no events are enabled. You can set and query the event mask attribute while a UMSImagePlayer is in any state.
The pending event attribute defines whether a UMSImagePlayer event is available and if so, the contents of the event. You can query the existence of a pending event using the event_pending() method. The event_pending() method can be called for a UMSImagePlayer in any state.
You can remove a UMSImagePlayer's pending event using the get_event() method which returns the contents of the pending event. The get_event() method can be called for a UMSImagePlayer in any state. However, if called in the ReadingState while no event is pending, the get_event() method blocks (does not return control to your application) until an event is received. If called in any other state while no event is pending, the get_event() method returns the NoEvent return code.
The event handle attribute defines a file descriptor you can use to query for and block on UMSImagePlayer events. You can obtain an event handle from a UMSImagePlayer in any state.
A UMSImagePlayer maintains each of the attribute defined below for each of a UMSImagePlayer's images. For example, each of the UMSImagePlayer's images has a subimage rectangle attribute. The UMSImagePlayer's current image attribute is used to address a particular image to query or set the image's attributes. For example; 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 use 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 the file.
The current image's information attribute contains any information associated with the current image. For example, it can contain information about how the image was created and what the image represents. The content and format of the information is image-specific and can be null. See "Current Image's Copyright Information " for copyright specific information and "Image File Info" for information related to the UMSImagePlayer's open image file.
You can query the current image's Information while a UMSImagePlayer object is in the ReadyState, ReadingState, or DisplayingState.
The current image's copyright information attribute contains any copyright information associated with the current image. You can query the current image's copyright information while a UMSImagePlayer object is in the ReadyState, ReadingState, or DisplayingState.
The current image's arbitrary scaling support attribute defines whether a UMSImagePlayer supports arbitrary scaling of the current image. When TRUE, you can set the current image's display size attribute to an arbitrary value and the UMSImagePlayer scales the current image to fit within the specified display size.
You can query the current image's arbitrary scaling support attribute when the UMSImagePlayer's is in any state, but the value of the attribute is always FALSE if the UMSImagePlayer is in the NotReadyState.
The current image's color properties support attribute defines whether a UMSImagePlayer supports setting the current image's color properties to values other than the default. For more information on color properties, see "Current Image's Color Properties" .
You can query the current image's color properties support attribute when the UMSImagePlayer's is in any state, but the value of the attribute is always FALSE if the UMSImagePlayer is in the NotReadyState.
The current image's transforms support attribute defines the image transformations supported by a UMSImagePlayer's current image. For more information, see "Current Image's Transform" .
The current image's transforms support attribute can be queried when the UMSImagePlayer's is in the ReadyState, ReadingState, or DisplayingState.
The current image's subimage rectangle attribute defines the portion of the current image which a UMSImagePlayer actually displays. You can define the current image's subimage rectangle in either the current image's source coordinate system or the current image's destination coordinate system (as specified by a flag on the set_subimage() method). The source coordinate system is defined by the current image's size attribute with the origin in the upper left corner of the source image. The source coordinate system does not include any transformations, such as rotations or scaling. The destination coordinate system is defined by the current image's display size and transformation attributes and therefore does reflect the transformations, such as scaling and rotation, applied to the Current Image as the image is mapped from the source coordinate system to the display coordinate system. The origin of the destination coordinate system is the upper left corner of the current image after the image has been transformed. The two coordinate systems are shown in the following figure.
To set the current Image's subimage rectangle, the UMSImagePlayer object must be in the ReadyState, ReadingState, or DisplayingState.
The current image's window attribute defines the current image's Xwindow identifier. By default, the window attribute of each of the UMSImagePlayer's images is undefined and therefore, by default, none of a UMSImagePlayer's images are displayed. To display one or more of a UMSImagePlayer's images, you must set the image's window attribute using the set_current_image() and set_window() methods. To stop the display of a specific image, use the set_current_image() and release_window() methods. The release_window() method resets the current image's window attribute to UNDEFINED.
You must first set the UMSImagePlayer's display attribute before setting an image's window attribute. Also, the window ID you specify to the set_window() method must represent a window created on the display specified by the display attribute. If you change the UMSImagePlayer's display attribute, all of the window attributes associated with the UMSImagePlayer's images are reset to UNDEFINED.
To set or query the current image's window attribute, a UMSImagePlayer must be in either the ReadyState, ReadingState, or DisplayingState. If you set the current image's window attribute while the UMSImagePlayer is in the ReadingState or DisplayingState, the image is read and displayed in the specified window if the window is "mapped." If you set the current image's window attribute while the UMSImagePlayer is in the ReadyState, the image is displayed the next time your application calls the start_display() method.
The current image's sizes attribute contains the set of image sizes (resolutions) defined for the current image. If the current image has multiple sizes, your application can use the current image's size attribute to choose the image size a UMSImagePlayer uses when reading the current image from an open image file. The actual display size of the current image is defined by the current image's display size attribute, which can differ from the current image's size if the UMSImagePlayer supports arbitrary image scaling.
Note that the current image's transform attribute affects the current image's display size attribute. Specifically, when you change the current image's transform, the current image's display size attribute is rotated to reflect the current image's transform attribute. For example, if you set the current image's transform attribute to ROTATE_0 (zero degrees of rotation), set the current image's display size to 16x32, then set the current image's transform attribute to ROTATE_90 (a 90 degree rotation), the current image's display size attribute is automatically set to 32x16 (a 90 degree rotation).
To query the current image's sizes, size, or display size the, UMSImagePlayer must be in either the ReadyState, ReadingState, or DisplayingState.
The current image's colormap attribute defines the colormap the UMSImagePlayer uses when displaying the current image in the current image's window.
The current image's colormap attributes attribute defines the size and base index of the current image's colormap.
The current image's X colormap id attribute defines the X resource ID of the current image's colormap.
Only indexed images uses a colormap, so if the current image is not indexed, you need not bother with the current image's colormap, colormap attributes, or X colormap Id attributes. Use the X visual of the current image's window attribute to determine whether the current image is indexed or direct.
By default, each of the UMSImagePlayer's indexed images has a default colormap defined by the image's format. In other words, the layout of the colors in an image's default colormap are image-format specific. Some image formats allow you to specify a colormap (which can be restricted in the number of entries for example); others require you to use the image's default colormap.
For those image formats which allow you to change the current image's colormap, you can choose to either change the colormap or use the default colormap when displaying the image. If you choose to use the default colormap and would like to know what the colormap is, call the get_colormap_attributes() and get_colormap() methods to retrieve the current image's colormap. You can also retrieve the current image's X colormap ID attribute using the get_colormap_id() method.
If you choose to change the colormap, use the set_colormap_attributes() method and either the set_colormap() or set_colormap_id() methods. If the current image's colormap is restricted in any way, the set_colormap_attributes(), set_colormap(), and set_colormap_id() methods return the colormap attributes, colormap, and X colormap ID the UMSImagePlayer actually uses when displaying the current image.
The current image's colormap, colormap attributes, and X colormap ID attributes can only be set when a UMSImagePlayer is in the ReadyState, ReadingState, or DisplayingState.
The current image's transform attribute defines the absolute transformation a UMSImagePlayer applies when displaying the current image. By default, the current image's transform attribute is equal to the current image's right-side-up transform so that the current image is displayed, by default, right-side-up. Some image formats do not support the concept of a right-side-up transformation. Therefore, images defined in those formats may not appear to you to be right-side-up.
You can query the current image's transform only while a UMSImagePlayer is in the ReadyState, ReadingState, or DisplayingState.
The current image's right-side-up transform attribute defines the transformation required to display the current image right-side-up. By default, the current image's transform attribute is equal to the current image's right-side-up transform so that the current image is displayed, by default, right-side-up. Some image formats do not support the concept of a right-side-up transformation. Therefore, images defined in those formats may not appear to you to be right-side-up.
You can query the current image's right-side-up transform only while a UMSImagePlayer is in the ReadyState, ReadingState, or DisplayingState.
The current image's associated Image Path attribute defines the pathname of a file associated with a UMSImagePlayer's current image. Typically, the attribute is used to determine the name of a file containing the a high resolution image associated with a thumbnail-size image. Not all images have an associated pathname; therefore, the current image's associated image pathname attribute can be NULL.
You can query the current image's associated image pathname only while a UMSImagePlayer is in the ReadyState, ReadingState, or DisplayingState.
The current image's color properties attribute defines shifts in the red, green, and blue color components applied to an the current image when displayed by a UMSImagePlayer. You use the properties to adjust the color balance, lightness, and saturation of the current image. Be default, the color properties of an image are unmodified (set to all zeros).
Some image formats do not support control over an image's color properties. Therefore, for some image formats, a UMSImagePlayer's supports color properties attribute is False which means that the UMSImagePlayer does not allow an image's default color properties to change. For more information on the supports color properties attribute, see "Current Image's Color Properties Support" .
You can set or query the current Image's color properties while a UMSImagePlayer is in the ReadyState, ReadingState, or DisplayingState.
