DLImageFactory Class Reference

A singleton object which handles loading and saving of images for DLImage. More...

#include <DLImageFactory.h>

List of all members.

Public Member Functions

DLImage dlLoadImageAtPage (const char *filename, int pageNumber)
DLImage dlLoadImageAtPage (const void *pMemLoc, int nSize, int pageNumber)
DLImage dlLoadImage (const char *filename, DLBaseImage *imageType=NULL)
DLImage dlLoadImage (const void *pMemLoc, const int nSize, DLBaseImage *imageType)
void dlSaveImage (const DLImage &image, const char *filename, DLBaseImage *imageType=NULL)
void * dlSaveImageToMem (const DLImage &image, int &nSize, DLBaseImage *imageType)
void dlShowAllRegistered ()
vector< DLBaseImage * > dlGetRegisteredImageObjects () const
int dlGetTotalPages (void *pMemLoc, int nSize)
int dlGetTotalPages (const char *filename)
DLBaseImagedlIdentifyImageType (const void *pMemLoc, const int nSize)
DLBaseImagedlIdentifyImageType (const char *filename)

Static Public Member Functions

static void dlRegisterImageType (DLBaseImage *image)
static DLImageFactorydlGetInstance ()


Detailed Description

A singleton object which handles loading and saving of images for DLImage.

DLImageFactory is used internally by DOCLIB to support the loading and saving of images in a variety of file formats. DOCLIB programmers should first see DLImage for the typical DOCLIB programming interface for loading and saving images.

DLImageFactory keeps tracks/manages all supported image objects in in a list and is populated during run time. DLImageFactory provides a registration API which allows image objects, in the form of DLBaseImage base class pointers to register and be included as a supported DOCLIB image type.

Each supported image format is subclassed from DLBaseImage (e.g. DLBMPImage, DLTIFFImage) and implemented as a singleton: the single static instance of the image format object must be initialized at file scope in the image format class. To ensure that all supported image formats are available to the DOCLIB programmer, DLImage includes the header file DLSupportedImages.h, which in turn includes the several image format class header files. Including the class header file triggers the construction of the image format object; upon construction, the object registers itself with DLImageFactory by providing a base class DLBaseImage pointer.

When one of the DLImage load functions is called, the request is passed to DLImageFactory, which uses dlIdentifyImageType() to determine if the image file or buffer is supported by any of the registered image formats. If the load function is called for a file name, the DLImageFactory first attemps to load it by its extension. If that fails, or if the load function is called for a memory buffer, the DLImageFactory will loop through all of the registered image format pointers, and ask each image format object if it can load the file or buffer in question. The first one to match will load the image; if none can load it, a DLException will be thrown.

Definition at line 61 of file DLImageFactory.h.


Member Function Documentation

DLImage DLImageFactory::dlLoadImageAtPage ( const char *  filename,
int  pageNumber 
)

Loads a particular page of a multi-page image from a file. DLImage factory will call the individual image types to perform this task.

Parameters:
filename name of image file to be opened
pageNumber the page number to be opened
Returns:
DLImage of particular page

DLImage DLImageFactory::dlLoadImageAtPage ( const void *  pMemLoc,
int  nSize,
int  pageNumber 
)

Loads an image from a memory buffer at a particular page. DLImage factory will call the individual image types to perform this task.

Parameters:
pMemLoc pointer to beginning of memory image buffer to be opened
nSize size of memory buffer in bytes
pageNumber number of page to be opened
Returns:
DLImage of particular page

DLImage DLImageFactory::dlLoadImage ( const char *  filename,
DLBaseImage imageType = NULL 
)

Loads an image from a file. The function first checks if the image object specified (imageType) is the correct image object. If an image object is not specified or the specified image object is incorrect, DLImageFactory then loops through all the registered image objects and determines whether the file is of that type by calling DLBaseImage::dlSupportImageFile(). Once the supported image object is found, it will perform the image loading.

Parameters:
filename file name to open
imageType Image format object used to load the file
Returns:
DLImage from file

DLImage DLImageFactory::dlLoadImage ( const void *  pMemLoc,
const int  nSize,
DLBaseImage imageType 
)

Loads an image from a memory buffer. The function first checks if the image object specified (imageType) is the correct image object. If an image object is not specified or the specified image object is incorrect, DLImageFactory then loops through all the registered image objects and determines whether the file is of that type by calling DLBaseImage::dlSupportImageFile(). Once the supported image object is found, it will perform the image loading.

Parameters:
pMemLoc pointer to beginning of buffer
nSize size of buffer in bytes
imageType Image format object used to load the file
Returns:
DLImage from memory buffer

void DLImageFactory::dlSaveImage ( const DLImage image,
const char *  filename,
DLBaseImage imageType = NULL 
)

Saves an image to a file. If an image format object is specified, it will be used to do the saving. Otherwise, the image format object correspoding to the extension of the filename provided is used to perform the save.

Parameters:
image DLImage to save to file
filename file name to save to
imageType Image format object used to save the file

void* DLImageFactory::dlSaveImageToMem ( const DLImage image,
int &  nSize,
DLBaseImage imageType 
)

Save an image to memory.

The image format object must be sent (unlike when writing to file)

Parameters:
[in] image DLImage to save to memory buffer
[out] nSize this is where the buffer length will be returned)
[in] imageType pointer to image format object
Returns:
pointer to memory buffer in which the image was saved
Exceptions:
DL_NOT_SUPPORTED_EXCEPTION 

void DLImageFactory::dlShowAllRegistered (  ) 

Dump information about all supported image formats to the DLLogger at level DLLogger::DL_INFO.

vector<DLBaseImage*> DLImageFactory::dlGetRegisteredImageObjects (  )  const [inline]

Return all supported image objects. User can loop through the vector to access each of the objects.

Returns:
vector of all supported image objects as base class (DLBaseImage) pointers

Definition at line 191 of file DLImageFactory.h.

static void DLImageFactory::dlRegisterImageType ( DLBaseImage image  )  [static]

Registers a supported image type with the image factory. DLImageFactory will use all the registered image objects when loading and saving images. This function will create the single instance of the DLImageFactory object if it does not yet exist.

Parameters:
image pointer to image format object to be registered.

int DLImageFactory::dlGetTotalPages ( void *  pMemLoc,
int  nSize 
)

Get the total number of pages in an image stored in a memory buffer.

Parameters:
pMemLoc pointer to beginning of buffer
nSize size buffer in bytes
Returns:
the total number of pages

int DLImageFactory::dlGetTotalPages ( const char *  filename  ) 

Get the number of pages in an image file.

Parameters:
filename name of image file to check
Returns:
the total number of pages

DLBaseImage* DLImageFactory::dlIdentifyImageType ( const void *  pMemLoc,
const int  nSize 
)

Identifies the type of image stored in a memory buffer. Returns a base class pointer to the appropriate image format object, or a NULL pointer if no image format matches.

Parameters:
pMemLoc pointer to beginning of memory buffer
nSize size of buffer in bytes
Returns:
base class (DLBaseImage) pointer to image format object

DLBaseImage* DLImageFactory::dlIdentifyImageType ( const char *  filename  ) 

Identifies the type of image stored in a file. Returns a base class pointer to the appropriate image format object, or a NULL pointer if no image format matches.

Parameters:
filename name of file to check
Returns:
base class (DLBaseImage) pointer to image format object

static DLImageFactory* DLImageFactory::dlGetInstance (  )  [static]

Returns a pointer to the only instance of DLImageFactory. If the DLImageFactory instance does not exist, it will create an instance and return it.


The documentation for this class was generated from the following file:

DOCLIB is being developed under contract by a collaboration between:
The Laboratory for Language and Media Processing
Unviersity of Maryland, College Park
and
Booz | Allen | Hamilton

All Rights Reserved, 2003-2007