The UMSPCDImageReader object is an Ultimedia Services Version 2 feature and does not apply to Ultimedia Services Version 1.2.1.
Photo CD provides methods for encoding and retrieving high resolution digital image data and other digital data from multisession CD-ROM/XA drives. Support for Photo CD on AIX consists of software that allows image data files on Photo CD discs to be read and displayed on AIX workstations.
The UMSImageReader methods can be used on all supported image file formats. Additional, Photo CD-specific methods are available in three derived image reader objects: the UMSPCDImageReader, UMSPCDIPImageReader, and UMSPCDOImageReader objects. These methods are generally based on functions available in the Kodak Photo CD Access Developer Toolkit for Unix systems. Detailed descriptions of these additional methods are beyond the scope of this manual; for further information, consult the Kodak documentation for the Access toolkit (hereafter referred to in this documentation as the toolkit).
Note that applications should not instantiate UMSPCDImageReader objects; image reader objects should be instantiated only from the UMSImageReader, UMSPCDIPImageReader, and UMSPCDOImageReader classes. For further information, see "Guidelines for Programmers" .
To learn more about Photo CDs and the UMSPCDImageReader object, see:
For introductory information, see Formatted File Access Objects.
A Photo CD is accessed as a mounted file system located on a CD-ROM XA drive. (A Photo CD on a CD-ROM XA drive can be mounted as a file system using the command smit cdrfs.) AIX Version 4 or later supports mounting a CD-ROM XA disc as a file system; earlier versions of AIX do not include such support. Consequently, AIX Version 4 or later is a prerequisite for AIX Photo CD support, and the Photo CD must be mounted as a file system on the CD-ROM XA drive.
A Photo CD image is composed of a rectangular array of square pixels in Kodak's Photo YCC format. Pixels are arranged on a square grid. As the number of pixels per line always equals 1.5 times the number of lines per image, the image aspect ratio is 2:3. There are 7 Photo CD image resolutions supported on AIX.
| Photo CD Image Resolutions supported On AIX | |
| Format Name | Pixels Per Line by Lines Per Image |
| Base/64 | 96 x 64 |
| Base/16 | 192 x128 |
| Base/4 | 384 x 256 |
| Base | 768 x 512 |
| 4 Base | 1536 x 1024 |
| 16 Base | 3072 x 2048 |
| 64 Base | 6144 x 4096 |
The Photo CD specification includes support for a range of formatted CD-ROMs. Perhaps the three most common ones are Portfolio, Master, and Pro discs. Photo CD Portfolio discs contain Image Pacs with three resolutions: Base/16, Base/4, and Base. Photo CD Master discs contain Image Pacs with five resolutions: Base/16, Base/4, Base, 4Base, and 16Base. Photo CD Pro discs contain Image Pacs with six resolutions: the five found on Photo CD Master discs plus 64Base. In order to read complete 64Base images, your system must have approximately 130 megabytes of free page space.
Files on a Photo CD are stored in a hierarchical file structure. At least two subdirectories are present in the Photo CD's root directory. The first directory, photo_cd, contains the digital Photo CD images and all associated data. The second directory, cdi, contains similar information for use on CDI systems, and is not discussed further in this document. All data used by the AIX Photo CD software reside in the directory photo_cd.
Three files with an extension of pcd reside in the photo_cd directory. The first one, overview.pcd, contains a thumbnail (such as, Base/16) view of each image contained on a Photo CD. The second file, start_up.pcd, is the first image that a Photo CD player displays; it contains the photo CD logo. The third file is info.pcd, which contains serial numbers and information about the Photo CD and the photographic lab that processed it.
Information about copyright and use restrictions can be stored as files in the directory photo_cd/rights.
The individual images are stored in the directory photo_cd/images. The naming convention for images is img<nnnn>.pcd, where <nnnn> is a unique number associated with a single Image Pac. For example, img0001.pcd is the name of the first image file on a Photo CD. The following figure shows the file structure of a Photo CD.
Note: The figure shows only a partial view of a Photo CD file system; a Photo CD can contain other elements that are not shown. These additional elements can include audio files and playlist files. This release of AIX Photo CD software does not include support for these additional elements; therefore, they are not shown in the figure.
Photo CD images are always stored in landscape orientation, regardless of where the "top" of the picture is. This is referred to as the reference orientation.
The coordinate conventions for the Photo CD toolkit software specify that the coordinate system used is in pixels; the origin is at the upper-left corner of the image. Positive directions are to the right and down. Rectangles are specified by the coordinates of their upper-left and lower-right corners. For instance, the coordinates of a 300 x 200 pixel rectangle are 0,0 and 299,199. See the following figure.
typedef struct {
short BrightButton; /* Brightness button value */
short RedButton; /* Red Color button value */
short GreenButton; /* Green Color button value */
short BlueButton; /* Blue Color button value */
short SatButton; /* Saturation button value */
short OutOfGamut; /* 1 = show, 0 = don't show */
short SubtractSBA; /* 1 = subtract SBA, 0 = don't subtract SBA */
} PCDbuttonRec
typedef struct pcdinfofilerec {
char signature[8];
unsigned char majorRevision;
unsigned char minorRevision;
char serialNumber[12];
unsigned long creationTime;
unsigned long modificationTime;
unsigned short nImages;
unsigned char interleaveRatio;
unsigned char resolution;
unsigned char leadOutStartTime[3];
unsigned char nSessions;
}*PCDinfoFileRec;
When declaring the variable of PCDbuttonRec and PCDinfoFileRec type, the actual C language declarations prepends the string UMSPCDImageReader_ to the declarations. (For example, UMSPCDImageReader_PCDbuttonRec).
enum resolutions {
PCD_BASE_OVER_64, /* 64 x 96 */
PCD_BASE_OVER_16, /* 128 x 92 */
PCD_BASE_OVER_4, /* 256 x 384 */
PCD_BASE, /* 512 x 768 */
PCD_4BASE, /* 1024 x 1536 */
PCD_16BASE, /* 2048 x 3072 */
PCD_64BASE /* 4096 x 6144 */
}
The Photo CD Image Reader methods include the following additional methods beyond those described in "UMSImageReader Object" . The following methods are common to all PhotoCD image classes.
This method sets the offset in bytes between color planes and the offset in bytes between adjacent pixels. These values are used with read_image. They are ignored for all 8-bit data formats. The default value for planeOffset is 1 and for pixelOffset is 3. All values are accepted on the assumption that some unusual memory layouts can be desired. See the table in get_image_attributes.
The method gets the current settings for the offset in bytes between color planes and the offset in bytes between adjacent pixels.
Note: The set_image_attributes and get_image_attributes do not need to be called in the normal course of reading Photo CD image data because selection of the format sets the internal state represented by planeOffset and pixelOffset. The following table specifies the settings of planeOffset and pixelOffset for each supported format:
| Settings of planeOffset and pixelOffset | ||
| Format | planeOffset | pixelOffset |
| IF_PCDYCC24 | 1 | 3 |
| IF_RGBPacked24 | 1 | 3 |
| IF_RGB24Plane | number of pixels in image | 1 |
| IF_RGB24 | 1 | 4 |
| IF_PadRGB24 | 1 | 4 |
| IF_RGB8Dither | 1 | 1* |
| IF_Grayscale8 | 0 | 1* |
*Because of internal code requirements, the default state for pixelOffset in the case of IF_RGB8Dither and IF_Grayscale8 is 3, and get_image_attributes reports 3, but logically the correct value for these two formats is 1, hence its specification in the table above.
| out unsigned long planeOffset | planeOffset returns the number of bytes between image data color planes. |
| out unsigned long pixelOffset | pixelOffset returns the number of bytes between image data pixels. |
The method sets the number of bits allocated to the red, green, and blue color components. These are the number of bits considered significant when reducing 24-bit RGB images to 8-bit indexed images. The default values are 3-3-2. The sum of the values must be 8. You specifie the desired values in the in parameters; the actual values set are returned in the out parameters. The method uses the current color map; it fails if a color map is not currently installed.
The method gets the number of bits currently allocated to the red, green, and blue color components. These components are used when reducing 24-bit RGB images to 8-bit indexed images.
The method specifies a look-up table (LUT) for an image object. To select or reselect the default LUT, set lut._length to 0. The LUT specified is used during the conversion of a YCC image to RGB, which is done by read_image when a RGB color format is specified, and by convert_ycc_to_rgb during the conversion of an in-memory YCC image. Note that the method allocates its own memory and copies the entire LUT identified by lut to this memory.
| in sequence<octet> lut | lut points to a buffer containing the desired look-up table for an image reader. |
The method returns a pointer to memory containing a copy of the LUT currently specified for the image object and the number of entries in the LUT. The return of a NULL in lut._buffer indicates that the default LUT is in use; in this case, lut._length is undefined.
| out sequence<octet> lut | lut points to a buffer containing the current look-up table for an image reader. |
The method specifies the color button values to be used when image data is converted from YCC to RGB format. buttonValues controls red, green, and blue color balance, overall image lightness, and color saturation. It also includes scene balance adjustment (SBA) and out-of-gamut color controls.
| in PCDbuttonRec *buttonValues | buttonValues specifies the desired color button values to be used when image data is converted from YCC to RGB format. |
The method gets the color button values currently specified for an image and copies them into the structure identified by buttonValues.
| out PCDbuttonRec *buttonValues | buttonValues specifies the current color button values to be used when image data is converted from YCC to RGB format. |
The method reads the information file for a Photo CD into a user-provided buffer. path is a pointer to a null-terminated character string that is the path name of a info.pcd file. The method allows a disc to be identified uniquely.
| in string path | path is a pointer to a string that is the path name of an info.pcd file. |
| out PCDinfoFileRec info | info returns a pointer to a buffer that contains the contents of an info.pcd file. |
The method returns the current version number of the toolkit software.
| out short version | version returns the current version of the toolkit software. |
The method is used to determine the short filename of the image file associated with any currently selected thumbnail image. In Photo CD, this would return the short filename of the Image Pac associated with the currently selected thumbnail. If there is no associated image file, the method returns NULL. (This would be the case if the currently selected image was an Image Pac and get_friend was called.) The method allocates filename; the caller deallocates it.
Note: out string filename translates to char **filename in C.
| out string filename | filename returns the short filename of the image file associated with any currently selected thumbnail image. |
The method takes as input a UMSImageSize structure that specifies the size of an image. It returns the resolution enumeration that corresponds to this size. The method ignores the current image transform. (This is necessary because the enumerated types also ignore the current transform.) It returns an error if the enumeration is not one of the Photo CD enumerations.
| in UMSImageSize size | size specifies an image size. |
| out resolutions resolution | resolution returns the resolution enumeration that corresponds to the size specified by argument size. |
The method takes as input a Photo CD resolution enumeration and returns the UMS image size that corresponds to the enumeration. The method ignores the current transform of the image. It returns an error if the size does not match exactly one of the supported Photo CD resolutions.
Note: The performance of reading image data is affected by the scan direction of the image. If the image is read as a series of rectangular slices, the slices should be read oriented parallel to the long dimension of the image. (Image scan lines are always parallel to the long dimension of the image, regardless of whether the image is portrait or landscape.) In particular, this means that you get higher performance if you design your application to use vertical slices for portrait images.
The method converts pixCount pixels on an in-memory YCC image in inBuffer to RGB data and places it into outBuffer. The color button values and LUT currently set for the image are used during the conversion. The memory layout of inBuffer is described by inPlaneBytes and inColumnBytes. The desired memory layout in outBuffer is described by outPlaneBytes and outColumnBytes. The caller allocates outBuffer. The image can be converted without allocating additional memory if the memory layouts of the input and output images are the same. Both RGB and YCC images have a color depth of 8 bits per pixel component.
An image can be converted in place without allocating additional memory. For in-place conversion, memory layouts of the input and output images must be the same. convert_ycc_to_rgb can handle images with additional pixel components (such as an alpha mask channel), provided that correct values for the buffer pointers, plane bytes, and column bytes arguments are specified. The value of inBuffer->_buffer must point to the first Y pixel component. The value of outBuffer->_buffer must point to the first R pixel component. Any additional components must be transferred and possibly converted from inBuffer to outBuffer by the caller.
The method converts pixCount pixels of YCC data in inBuffer to RGB data using the default color-rendering values of the toolkit and places the RGB data into outBuffer. The memory layout of inBuffer is specified by the inPlaneBytes and inColumnBytes parameters. The desired memory layout of outBuffer is specified by outPlaneBytes and outColumnBytes. The caller allocates outBuffer. The image can be converted without allocating additional memory if the memory layouts of the input and output images are the same, and the in and out plane and column byte parameters are the same. The method uses default color-rendering values, which cannot be changed by the caller. The method returns an error when invoked on a PCDOO.
The method produces a dithered binary image (1-bit per pixel) from src, the Y component of a YCC (color) or Y-only (gray scale) image or a rectangular portion of it. The source Y or YCC image is usually produced by read_image. In the output image dst, pixels are packed 8 per byte. The caller allocates dst, and the memory identified by dst must start on an even byte boundary.
The method converts a 24-bit color image to 8 bits per pixel. It uses the color map specified by set_colors. inBuf must be in three-color interleaved format, and the data format must be "RGBPacked24" (in other words, planeOffset = 1 and pixelOffset = 3). The caller allocates outBuf, which must be at least height * width bytes.
For introductory information, see Formatted File Access Objects.