molib documentation

Languages Available: français español

CLASS

moImageBase

NAME

private:
Init - initialize an image structure

VERSION

Version: 1.2.0

SYNOPSIS

void Init(void);

DESCRIPTION

This function is used internally so all constructors can initialize the image object the same way.

The base init is called by the moImageBase constructor, which will be called before the moImage, moImage16 and moImageFloat contructors.

SEE ALSO

Constructor

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

moImageBase
moImage
moImage16
moImageFloat

NAME

Constructor - initialize or copy an image
Destructor - release all the resources used by an image

operator = - copy an image (with format convertion when required)

VERSION

Version: 1.2.0

SYNOPSIS

moImage(void);
moImage16(void);
moImageFloat(void);
moImage(const moImage& im);
moImage(const moImage16& im);
moImage(const moImageFloat& im);
moImage16(const moImage& im);
moImage16(const moImage16& im);
moImage16(const moImageFloat& im);
moImageFloat(const moImage& im);
moImageFloat(const moImage16& im);
moImageFloat(const moImageFloat& im);
moImage(unsigned long width, unsigned long height);
moImage(unsigned long width, unsigned long height, const moRGBA& clear);
moImage16(unsigned long width, unsigned long height);
moImage16(unsigned long width, unsigned long height, const moRGBA16& clear);
moImageFloat(unsigned long width, unsigned long height);
moImageFloat(unsigned long width, unsigned long height, const moRGBAFloat& clear);
virtual ~moImageBase();

moImage& operator = (const moImage& im);
moImage& operator = (const moImage16& im);
moImage& operator = (const moImageFloat& im);
moImage16& operator = (const moImage& im);
moImage16& operator = (const moImage16& im);
moImage16& operator = (const moImageFloat& im);
moImageFloat& operator = (const moImage& im);
moImageFloat& operator = (const moImage16& im);
moImageFloat& operator = (const moImageFloat& im);

PARAMETERS

im - an image to duplicate
width - the new image width
height - the new image height
clear - the color used to clear the new image

DESCRIPTION

The moImage constructors will be used to create new images or copy an existing image in a new image object. The function used without parameters creates an image holder. There won't be any data and the image sizes will be (0, 0).

The function which accepts an image as a parameter will duplicate that image in the new object. The function accepts sizes and possibly a color (clear) will be used to create an image with these sizes and possible clears it with the specified color (by default an image is not cleared).

The destructor ensures all the resources used by the image are released back to the system.

NOTES

It is possible to create an empty image in which case no resource are allocated. If either the width or height is zero, then the other is set to zero also.

SEE ALSO

Init

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageBase
moImage
moImage16
moImageFloat

NAME

SetSize - set/change the size of the image

VERSION

Version: 1.2.0

SYNOPSIS

void SetSize(unsigned long width, unsigned long height, bool safe = false);

protected:
void NewSizeCopy(unsigned char *data, unsigned long width, unsigned long height);

PARAMETERS

data - a pointer to the image data
width - the new image width
height - the new image height
safe - make it as safe as possible for the data

DESCRIPTION

The SetSize() function will be used to change the sizes of an image. This function doesn't resize the image data, it only sets the size of the buffer to the given width and height.

When the safe flag is set to true the function keeps as much data as it possibly can in the process (i.e. the top left of the image remains the same). Note that setting the safe flag to true and elarging an image makes the new area undefined.

NOTES

A safer resizing of the image buffer will be archived with the use of the Crop() or Enlarge() functions instead. To resize the image data also, use the Resize() function.

SEE ALSO

Constructors, Crop

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moRGBA
moRGBA16
moRGBAFloat

NAME

CopyImageData - copy an area into another

VERSION

Version: 1.2.0

SYNOPSIS

template<class D, class S>
static void CopyImageData(D *destination, unsigned long dw, unsigned long dh,
const S *source, unsigned long sw, unsigned long sh,
long x, long y, long sx, long sy,
unsigned long width, unsigned long height);

PARAMETERS

destination - the destination buffer
dw - width of the destination buffer
dh - height of the destination buffer
source - the source buffer
sw - width of the source buffer
sh - height of the source buffer
x - position where to copy into the destination
y - position where to copy into the destination
sx - position where to copy from in the source
sy - position where to copy from in the source
width - the width to copy
height - the height to copy

DESCRIPTION

The CopyImageData() function duplicates the pixels defined by the (sx, sy, width, height) rectangle to the (x, y, width, height) rectangle in the destination.

The function takes care of clipping the rectangle as required to ensure that the copy doesn't read or write data outside the source and destination buffers. It is possible that the clipping results in no copy being performed at all.

Since it is a template, the source and destination can both be of any pixel type. The necessary convertions will automatically be applied.

SEE ALSO

ClearImage

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImage
moImage16
moImageFloat

NAME

OpenGLTexCompatible - ensure that the texture is compatible with OpenGL textures

VERSION

Version: 1.2.0

SYNOPSIS

void OpenGLTexCompatible(void);

DESCRIPTION

The OpenGLTexCompatible() function ensures that the image has a height which is an exact power of 2. Note that OpenGL textures do NOT need to have a width which is a multiple of 2 because you can specify the width of the image with a glPixelStore() call:

glPixelStorei(GL_UNPACK_ROW_LENGTH, texture_width);

Note that you still have to specify the width as a power of two to the texture loading function:

glTexImage2D(GL_TEXTURE_2D, 0, 4, my_image.WidthP2(), my_image.HeightP2(), 0, GL_RGBA, GL_UNSIGNED_BYTE, my_image.Data());

Once you are done, it is strongly suggested that you reset the pixel store value to the default:

glPixelStorei(GL_UNPACK_ROW_LENGTH, 0);

which cancels the feature.

NOTES

This function uses SetSize() and tells it that it is safe to copy the image data as is. This has the effect to enlarge the image if required. Note however that the part which is added to the image in this way will be garbage.

SEE ALSO

CopyImage, Resize, SetSize

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImage
moImage16
moImageFloat

NAME

Clear - clear the image with the given color

VERSION

Version: 1.2.0

SYNOPSIS

void Clear(const moRGBA& clear, long x, long y,
unsigned long width, unsigned long height);
void Clear(const moRGBA16& clear, long x, long y,
unsigned long width, unsigned long height);
void Clear(const moRGBAFloat& clear, long x, long y,
unsigned long width, unsigned long height);

template<class D, class C>
void ClearImage(D *d, unsigned long dw, unsigned long dh,
const C& clear, long x, long y,
unsigned long width, unsigned long height);

PARAMETERS

d - pointer to the image data
dw - width of the image data buffer
dh - height of the image data buffer
clear - the color to use to clear the image
x - the first pixel to clear horizontally
y - the first pixel to clear vertically
width - the number of pixels to clear horizontally
height - the number of pixels to clear vertically

DESCRIPTION

The Clear() function can be used to copy a color in a rectangle in an image. It is possible to use the ClearImage() template in order to use a different type for the image data and the color used to clear the image.

SEE ALSO

CopyImageData

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageBase
moImage
moImage16
moImageFloat

NAME

AlphaTest - test whether the entire image is a solid,
transparent or a combinaison or if it is empty
IsSolid - check whether all the pixels are non-transparent
IsTransparent - check whether all the pixels are 100%
transparent
IsCombinaison - check whether any pixel is neither solid
nor fully transparent

VERSION

Version: 1.2.0

SYNOPSIS

alpha_test_t AlphaTest(void) const;
bool IsCombinaison(void) const;
bool IsSolid(void) const;
bool IsTransparent(void) const;

DESCRIPTION

These functions check every pixel to know whether they all are solid or transparent. If a mix is found, the image is determined to be a COMBINAISON. If only solid pixels are found, the image is said to be SOLID. When all the pixels are transparent, the image is TRANSPARENT. If the image is empty, then this function returns EMPTY.

The function checks the solidity and transparency of pixels using the pixel IsSolid() and IsTransparent() functions.

An empty window is considered solid.

SEE ALSO

IsEmpty

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImageBase
moImage
moImage16
moImageFloat

NAME

ApplyAlpha - apply the alpha to the image color components

VERSION

Version: 1.2.0

SYNOPSIS

void ApplyAlpha(void);

DESCRIPTION

The ApplyAlpha() function multiply all the color components with their respective alpha channel information. This way you can use the source image as is when blending it with another image; this often eliminates artifacts when the image isn't rendered at an exact pixel position with OpenGL.

Whenever a source image has had its alpha channel applied, it needs to use the following blend mode in OpenGL:

glBlendFunc(GL_ONE, GL_ONE_MINUS_SRC_ALPHA);

Also, images saved in a Flash movies with an alpha channel need to have their color components premultiplied in this way.

SEE ALSO

AlphaTest

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImage
moImage16

NAME

Histogram - count all the colors of the image

VERSION

Version: 1.2.0

SYNOPSIS

moArray *Histogram(void) const;

DESCRIPTION

This function can be used to count the colors present in an image. This will be used by different functions such as the Palette() function which generates a palette for an image.

It is the caller responsability to delete the array once it is not necessary any more.

NOTES

An empty image has no color and returns an empty array.

At this time there is no histogram for the floating point format since there can be a way too large number of color in such an image.

RETURN VALUE

The function returns an array of moCountColor[16].

SEE ALSO

Palette

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moImage

NAME

Paletize - transform an image in a palette of colors
and an array of indexes

VERSION

Version: 1.2.0

SYNOPSIS

void *Paletize8(unsigned long& count8) const;
void *Paletize16(unsigned long& count16) const;

PARAMETERS

count8 - the maximum number of colors to be returned
(usually 256 - supports any value from 16 to 256)

count16 - the maximum number of colors to be returned
(supports any value from 16 to 65536)

also the count8/count16 are set to the number of
colors defined in the resulting palette

DESCRIPTION

Whenever it is necessary to save an image in a file format which uses a palette and an array of indexes, one needs to call this function.

It will first count the total number of colors in an image. If that total is smaller or equal to the maximumm specified by the caller, then a palette is built from the existing colors and there won't be any loss of color information.

When there are too many colors, the function attempts to reduces them by grouping them. Groups are defined by transforming colors from the usual red, green, blue and alpha components to the most significant bits of each of these components to the least significant. By sorting the colors this way, groups are easilly generated. Clearing the four lower bits, then 8, 12, etc. we can merge the colors from different groups and generate a smaller number of colors.

NOTES

The function won't work very well when used to generate palettes with a very small number of colors (under 64).

It is possible to used a dithering to transform a color image in a black and white image.

The source image is not modified by this function.

There isn't such functions for the moImage16 since it doesn't seem necessary. You will have to convert you 16 bit image in an 8 bit first.

RETURN VALUE

0 if the function fails (empty image).

Otherwise the function returns an array of indexes. The
size of the indexes will be of 8 or 16 bits (an unsigned
char * or unsigned short * pointer). No palette of more
than 65536 colors can be created with this function.

SEE ALSO

Palette

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAME

moP2 - fast power of two computing

VERSION

Version: 1.2.0

SYNOPSIS

unsigned long moP2(unsigned long v);

PARAMETERS

v - value to transform in a power of two

DESCRIPTION

This function returns the closest logarithm of base 2 of the parameter value. The result is garantee to be large or equal to v up to 0x80000000.

RETURN VALUE

the power of 2 larger or equal to the input value if available

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox