Image data
Images can be created and/or manipulated within the Simplygon API using ImageData objects.
Texture images are stored in materials as ImageData objects. The image data objects are always three dimensional but for fewer dimensional representations the non-relevant axes are set to one. A 2d image of 256x256 pixels will thereby be a 3d matrix with dimensions 256x256x1. The dimensions of an ImageData are set with Set{1|2|3}DSize.
The pixels are either stored as 8 (TYPES_ID_UCHAR) or 16 (TYPES_ID_USHORT) bits per channel and the allowed color formats are RGB, RGBA, YUV, CMYK, L and R. The format is selected with AddColors.
To be able to manipulate the image pixels, they are read to an array using GetColors. The tuple size is determined by the color format (tuple size for RGB is 3) and the tuple count is the product of the image dimensions, e.g the number of pixels.
Supported image formats
Simplygon supports 8 and 16 bits per channel, that is 24 bpp and 48 bpp for RGB and 32 bpp and 64 bpp for RGBA textures.
The Simplygon SDK allows reading and writing of most common image formats listed below.
Format | Description | Extension |
---|---|---|
BMP | Windows or OS/2 Bitmap | BMP |
DDS | DirectX Surface (Load only) | DDS |
JPEG | JPEG - JFIF Compliant | JPG, JIF, JPEG, JPE |
PCX | Zsoft Paintbrush | PCX |
PNG | Portable Network Graphics | PNG |
TARGA | Truevision Targa | TGA, TARGA |
TIFF | Tagged Image File Format | TIF, TIFF |
Example - SetItem
This example shows how to generate a gradient image pixel by pixel using SetItem while the other example sets all the image data in one call using SetData.
spImageData GenerateGradientImage(unsigned int image_width, unsigned int image_height)
{
spImageData img = sg->CreateImageData();
// Set spImageData dimensions and color field with RGB format
img->Set2DSize(image_width, image_height);
img->AddColors(TYPES_ID_UCHAR, "RGB");
// Get the color array with tuple size 3
// and tuple count (image_width * image_height)
spUnsignedCharArray colors = SafeCast<IUnsignedCharArray>( img->GetColors() );
// Iterate over the image pixels and set the array values
for(unsigned int y = 0 ; y < image_height ; y++)
{
for(unsigned int x = 0 ; x < image_width ; x++)
{
// One dimensional index
int i = image_width * y + x;
// Gradient color
int gradient = x * 255 / image_width ;
// Colors to array
colors->SetItem(i*3+0, gradient);
colors->SetItem(i*3+1, gradient);
colors->SetItem(i*3+2, gradient);
}
}
return img;
}
spImageData GenerateGradientImage(uint image_width, uint image_height)
{
spImageData img = sg.CreateImageData();
// Set spImageData dimensions and color field with RGB format
img.Set2DSize(image_width, image_height);
img.AddColors((int)BaseTypes.TYPES_ID_UCHAR, "RGB");
// Get the color array with tuple size 3
// and tuple count (image_width * image_height)
spUnsignedCharArray colors = spUnsignedCharArray.SafeCast(img.GetColors());
// Iterate over the image pixels and set the array values
for (uint y = 0; y < image_height; y++)
{
for (uint x = 0; x < image_width; x++)
{
// One dimensional index
int i = (int)(image_width * y + x);
// Gradient color
int gradient = (int)(x * 255 / image_width);
// Colors to array
colors.SetItem(i * 3 + 0, (byte)gradient);
colors.SetItem(i * 3 + 1, (byte)gradient);
colors.SetItem(i * 3 + 2, (byte)gradient);
}
}
return img;
}
def GenerateGradientImage(sg, image_width, image_height):
img = sg.CreateImageData()
# Set spImageData dimensions and color field with RGB format
img.Set2DSize(image_width, image_height)
img.AddColors(Simplygon.TYPES_ID_UCHAR, "RGB")
# Get the color array with tuple size 3
# and tuple count (image_width * image_height)
colors = Simplygon.spUnsignedCharArray.SafeCast( img.GetColors() )
# Iterate over the image pixels and set the array values
for y in range(image_height):
for x in range(image_width):
# One dimensional index
i = image_width * y + x
# Gradient color, cast to int
gradient = int(x * 255 / image_width)
# Colors to array
colors.SetItem(i*3+0, gradient)
colors.SetItem(i*3+1, gradient)
colors.SetItem(i*3+2, gradient)
return img
Example - SetData
This example shows how to set all the image data in one call using SetData.
spImageData CreateRGBImage(unsigned int image_width, unsigned int image_height, unsigned char *data)
{
// Create an spImageData object
spImageData img = sg->CreateImageData();
// Set spImageData dimensions and color field with RGB format
img->Set2DSize(image_width, image_height);
img->AddColors(TYPES_ID_UCHAR, "RGB");
// Get the color array with tuple size 3 (RGB)
// and tuple count (image_width * image_height)
spUnsignedCharArray colors = SafeCast<IUnsignedCharArray>( img->GetColors() );
// Assign the data to the color field
colors->SetData(data, image_width * image_height * 3);
return img;
}
spImageData CreateRGBImage(uint image_width, uint image_height, byte[] data)
{
// Create an spImageData object
spImageData img = sg.CreateImageData();
// Set spImageData dimensions and color field with RGB format
img.Set2DSize(image_width, image_height);
img.AddColors((int)BaseTypes.TYPES_ID_UCHAR, "RGB");
// Get the color array with tuple size 3 (RGB)
// and tuple count (image_width * image_height)
spUnsignedCharArray colors = spUnsignedCharArray.SafeCast(img.GetColors());
// Assign the data to the color field
colors.SetData(data, image_width * image_height * 3);
return img;
}
def CreateRGBImage(image_width, image_height, values):
img = sg.CreateImageData()
# Set spImageData dimensions and color field with RGB format
img.Set2DSize(image_width, image_height)
img.AddColors(Simplygon.TYPES_ID_UCHAR, "RGB")
# Get the color array with tuple size 3
# and tuple count (image_width * image_height)
colors = Simplygon.spUnsignedCharArray.SafeCast( img.GetColors() )
# Assign the data to the color field
# Note that the array must be at least (image_width * image_height * 3) in size
colors.SetData(values, image_width * image_height * 3)
return img;