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 liste 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;