Skip to content
On this page

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.

FormatDescriptionExtension
BMPWindows or OS/2 BitmapBMP
DDSDirectX Surface (Load only)DDS
JPEGJPEG - JFIF CompliantJPG, JIF, JPEG, JPE
PCXZsoft PaintbrushPCX
PNGPortable Network GraphicsPNG
TARGATruevision TargaTGA, TARGA
TIFFTagged Image File FormatTIF, 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.

cpp
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;
}
csharp
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;
}
python
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.

cpp
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;
}
csharp
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;
}
python
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;