molib documentation

Languages Available: français español

CLASS

moImageFile

NAME

Constructor - initialize and register this image file format
Destructor - remove this image file format from the system list

VERSION

Version: 1.2.0

SYNOPSIS

moImageFile(void);
virtual ~moImageFile();

DESCRIPTION

The constructor of this object will ensure that the object is part of the list of file formats. This list is accessed each time an image file needs to be loaded or saved.

The list is sorted by MimeType(). If two objects with the same mime type are inserted in the list, then an error is thrown.

The destructor removes the object from the list since it can't be accessed anymore. This function is rather slow but it shouldn't be used except when people quit your application.

ERRORS

A throw occurs if two objects with the same mime type are created.

SEE ALSO

Load, Save, MatchType, MimeType

BUGS

The mime_type parameter to the constructor must be a constant string or a string which will leave for the time this object lives (i.e. the string is not copied in the object).

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFile

NAME

MimeType - returns the image file corresponding mime type

VERSION

Version: 1.2.0

SYNOPSIS

const char *MimeType(void) const;

DESCRIPTION

The MimeType() function returns the mime type.

SEE ALSO

Load, Save, MatchType

BUGS

The returned string has to live at least for the time the object exists. Callers will expect it to be that way.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFile

NAME

MatchPriority - priority over other image files formats
MatchType - checks whether the input buffer matches this
image type

VERSION

Version: 1.2.0

SYNOPSIS

virtual long MatchPriority(void) const = 0;
virtual long MatchType(const void *buffer, unsigned long size) const = 0;

PARAMETERS

buffer - a file buffer header
size - the number of valid bytes in the buffer

DESCRIPTION

The MatchType() function tests the input buffer within the constrained size for an image of the moImageFile object type. The function shall return a value from 0 to 100 (a percent). If 100 is returned, the fille is taken to be of that type. If a smaller value is returned, then the following image types are checked for a better percent value. The first object of which this function returns 100 or the object which returned the largest percent is selected as being the one which can load the specified image file.

Because some image formats can very well be identified, they have a much higher priority. Other file formats, those for which we can't be 100% sure the MatchType() will return a correct answer, will have a smaller priority.

In general, a standard type (recognized at 50%) will return a priority of 0 (such as TIFF which saves its header at the end of the file). A type which we are sure of will return a priority of +100 (such as GIF, PNG, JPEG). A type we are not sure about at all will return -100 (such as Targa).

The priority can also be used to sort the file types in such an order that most popular formats are tested first so the search for the proper format is faster.

SEE ALSO

Load, Save, MimeType

BUGS

Some image types don't save a magic number at the start and will therefore be detected as (1) not being another type or (2) having all their header being valid (proper sizes and parameters in general).

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFile

NAME

Load - load an image from a file
Save - save an image to a file

VERSION

Version: 1.2.0

SYNOPSIS

virtual bool Load(moIStream& file, moImage& im) = 0;
virtual bool Load(moIStream& file, moImage16& im);
virtual bool Load(moIStream& file, moImageFloat& im);
virtual bool Save(moOStream& file, const moImage& im) = 0;
virtual bool Save(moOStream& file, const moImage16& im);
virtual bool Save(moOStream& file, const moImageFloat& im);

PARAMETERS

file - a file where the image is read or written
im - the image loaded or to be saved

DESCRIPTION

The Load() function will be used to load an image from the input stream. When this function is called, the format of the input is already known since this function is only available on specific moImageFile objects. If you need to load images of different formats, you can let the system chosen which object to use to load your image. This is done with the static function moLoadImage().

The Save() function creates an image file. The format is already known since this function is only available on specific moImageFile objects. If you want to save to different image formats without having to decide which moImageFile object to create, use the moSaveImage() function and specify a MIME type instead.

The versions using an moImage16 format will be used to load images which support 16 bits. If a format doesn't support 16 bits then its 8 bits version will be used to load the image. Yet, a 16 bit image will be returned in the result. Similarly, it is possible to directly load an image of type moImageFloat.

The Load() function will possibly set some parameters in the image object to diverse values found in the image file. These are described on a per format basis. For instance, if a comment is found in the file, it is put as the parameter "COMMENT" in the list of parameters of the image object.

For some loaders it is also possible to affect the behavior of the loader by setting some parameters in the image object before to call the Load() function. Watch out! Such parameters may affect different loaders in a slightly different manner. It is wise at times to get a direct connection to a loader and use that instead of trying to wonder what is going to happen.

The Save() function will possibly use some parameters already set in the image object. It will never change or add any parameters. The values will be used to save the images in different sub-formats. For instance, a DEPTH of GREYSCALE will force the image to be saved as a greyscale image.

For the Save() function there are helper functions which will test some parameters which are common to different formats in order to know what they are set too. For instance, the DEPTH parameter can be set to GREY or GRAYSCALE and you will get the same effect. This specific parameter is tested in the DefineDepth() function.

SEE ALSO

DefineDepth, MatchType, MatchPosition, MimeType

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFile

NAME

DefineDepth - transform a depth name in a depth type

VERSION

Version: 1.2.0

SYNOPSIS

static mo_image_file_depth_t DefineDepth(const moImage& im, bool test_solid = false);

PARAMETERS

im - the image which depth parameter is checked out
test_solid - test whether the image is solid if no depth is defined

DESCRIPTION

The Save() functions will usually check out the DEPTH parameter of the image they are about to save. In order to do that in a rather consistant way, this function was created. It will transform the following named depth in the corresponding mo_image_file_depth_t type.

Type Names

MO_IMAGE_FILE_DEPTH_UNKNOWN none of the following

MO_IMAGE_FILE_DEPTH_BLACKNWHITE "BLACKNWHITE" "B&W" "BNW" "BW"

MO_IMAGE_FILE_DEPTH_PALETTED "PALETTED" "PALETTE"

MO_IMAGE_FILE_DEPTH_GREYSCALE "GREY" "GREYSCALE" "GRAY" "GRAYSCALE" "Y" "LUMINANCE"

MO_IMAGE_FILE_DEPTH_RED "RED" "R"

MO_IMAGE_FILE_DEPTH_GREEN "GREEN" "G"

MO_IMAGE_FILE_DEPTH_BLUE "BLUE" "B"

MO_IMAGE_FILE_DEPTH_ALPHA "ALPHA" "A" "TRANSPARENCY"

MO_IMAGE_FILE_DEPTH_GREYA "GREYA" "GREYALPHA" "GREYSCALEA" "GREYSCALEALPHA" "GRAYA" "GRAYALPHA" "GRAYSCALEA" "GRAYSCALEALPHA"

MO_IMAGE_FILE_DEPTH_RGB555 "RGB555"

MO_IMAGE_FILE_DEPTH_RGB5551 "RGB5551"

MO_IMAGE_FILE_DEPTH_RGB "RGB" "COLOR" "COLOUR"

MO_IMAGE_FILE_DEPTH_RGBA "RGBA" "COLORA" "COLORALPHA" "COLOURA" "COLOURALPHA"

SEE ALSO

DefineCompression, Save

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFile

NAME

DefineCompression - transform a compression name in a compression type

VERSION

Version: 1.2.0

SYNOPSIS

static mo_image_file_compression_t DefineCompression(const moImage& im);

PARAMETERS

im - the image which depth parameter is checked out

DESCRIPTION

The Save() functions will usually check out the COMPRESSION parameter of the image they are about to save. In order to do that in a rather consistant way, this function was created. It will transform the following named compressions in the corresponding mo_image_file_compression_t type.

In most cases, if only one compression is supported, the default compression (or best) will be used if the specified compression isn't understood. Only if you get a NONE will you not compressed (unless there is no compression support in the given format like PPM).

The special TEST entry will be used by formats which support multiple compression schemes to find the best one for the given image. This can take a long time since it will compress the image using each compression scheme then compare which one's best and keep that one.

Type Names

MO_IMAGE_FILE_COMPRESSION_UNKNOWN none of the following

MO_IMAGE_FILE_COMPRESSION_NONE "NONE" "VERBATIM"

MO_IMAGE_FILE_COMPRESSION_BEST "BEST"

MO_IMAGE_FILE_COMPRESSION_TEST "TEST"

MO_IMAGE_FILE_COMPRESSION_RLE "RLE"

SEE ALSO

DefineDepth, Save

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFile

NAME

Compare - compare two image file mime types
ComparePriority - compare two image file match priority

VERSION

Version: 1.2.0

SYNOPSIS

compare_t Compare(const moBase& object) const;
compare_t ComparePriority(const moBase& object) const;

PARAMETERS

object - another image file

DESCRIPTION

The Compare() function is used to sort the image file formats by their MIME types.

The ComparePriority() function is used to sort the image file formats by priority. This sorted list is used to quickly find a proper match of a file format from a file header.

SEE ALSO

Load, Save, MimeType, MatchType, MatchPriority, moFindImageFile

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFile

NAME

moLoadImage - load an image from a file
moSaveImage - save an image to a file

VERSION

Version: 1.2.0

SYNOPSIS

bool moLoadImage(moIStream& file, moImage& im);
bool moLoadImage(moIStream& file, moImage16& im);
bool moLoadImage(moIStream& file, moImageFloat& im);
bool moSaveImage(moOStream& file, const moImage& im, const char *mime_type = 0);
bool moSaveImage(moOStream& file, const moImage16& im, const char *mime_type = 0);
bool moSaveImage(moOStream& file, const moImageFloat& im, const char *mime_type = 0);

PARAMETERS

file - a file where the image is read or written
im - the image loaded or to be saved
mime_type - the image file format used to save the image in

DESCRIPTION

The Load() function will be used to load any image format currently supported by the library or loaded as plug ins.

The Save() function creates a file of the specified image file format from the given image.

It is possible to set the FILEFORMAT parameter in the image instead of using the mime_type parameter. Note that the loaders will set that parameter automatically. Thus, it is possible to load an image in a given format and by default it will be saved back in that same format.

The version with 16 bits images will load/save 8 bits images if the specified format doesn't allow for 16 bits. Then the image will automatically be transformed in a 16 bits image and returned to the caller.

SEE ALSO

Load, Save, MimeType, MatchType, MatchPriority, moFindImageFile

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFileFactory

NAME

RegisterFormat - call to register a new image format

VERSION

Version: 1.2.0

SYNOPSIS

void RegisterFormat(moImageFile *format);

static moImageFileFactorySPtr GetFactory(void);
static void Done(void);

private:
void InitLists(void);

PARAMETERS

format - format to register

DESCRIPTION

The moRegisterFormat() functions is used by each image file format supported to register themselves to the factory. The factory is in turn used to access to the different instances of each format.

The GetFactory() function will be used to access the image file factory. Note that there can be only one factory and for this reason, the function will automatically create one factory on the first call, and then always return the same factory over and over again.

In DEBUG mode, you may want to track the leaks and thus you can call Done() to clean up all the memory used by this class and all the registered classes.

Note that the GetFactory() function call will generate an assert after a call to the Done() function.

The GetMIMEList() function returns a list of image formats sorted by MIME

The very first time you try to access the list of available image formats, you get a call to the InitLists() which creates the f_mime_list and f_match_list.

RETURN VALUE

The GetFactory() function returns a smart pointer to the
moImageFileFactory for your process.

SEE ALSO

BUGS

The very first GetFactory() needs to be done before you create another thread which may also use it.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageFile

NAME

moFindImageFile - look for an image file format

VERSION

Version: 1.2.0

SYNOPSIS

moImageFile *moFindImageFile(const char *mime_type);
moImageFile *moFindImageFile(const void *buffer, unsigned long size);

PARAMETERS

buffer - size of the buffer to match for a type
size - the size of the buffer in bytes
mime_type - the mime type of the image file format seeked

DESCRIPTION

The moFindImageFile() functions will be used to search for an image file format among all the image file formats currently registered in the system which match the specified input parameter(s).

When a MIME is specified, the function compares each known image file format MIME type. Only one image file format can accept a given MIME type.

When a buffer and a size is specified, the function searches for a matching format. All the formats will always be tested unless one returns that it matched 100%.

SEE ALSO

MimeType, MatchType, MatchPriority, moLoadImage, moSaveImage

BUGS

At this time these functions are not safe in a multi-thread environment.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox