HOOPS Visualize Documentation

< Table of Contents

PROGRAMMING GUIDE

4.4 Images

4.4 Defining images

Images are defined in portfolios as a prerequisite to defining a texture. The most convenient way to import images into Visualize is to using the Image::File::Import function, although it is possible to use a programmatically-defined or generated image as texture data. Any byte array will work. Image files are loaded synchronously by Visualize, so if you expect image loading to take a long time, you should use a separate worker thread. The only requirements to specify when loading images are the filename and the image format. Any problems associated with loading an image will be reported using an Image::IOException.

[snippet 4.4.a]
ImageKit imageKit;
try
{
imageKit = Image::File::Import(filename, iok);
ImageDefinition imageDefinition = myPortfolio.DefineImage("my_image", imageKit);
}
catch (IOException ioe)
{
const char* problem = ioe.what(); // shows cause of the exception
}
ImageKit imageKit;
try
{
HPS.Image.ImportOptionsKit iok = new Image.ImportOptionsKit();
iok.SetFormat(HPS.Image.Format.Jpeg);
imageKit = Image.File.Import(filename, iok);
ImageDefinition imageDefinition = myPortfolio.DefineImage("my_image", imageKit);
}
catch (HPS.IOException ioe)
{
String problem = ioe.what(); // shows cause of the exception
}

Portfolio::DefineImage expects an ImageKit object as a parameter, which is returned by Image::File::Import. When defining an image in this way, only the image format and filename must be provided. However, it is possible to define an ImageKit manually. When defining images that are loaded without the use of Image::File::Import, the dimensions, the image format, and the image data itself must be supplied so that the kit can be composed. That operation is described below:

[snippet 4.4.b]
ImageKit imageKit;
imageKit.SetData(byteArray);
imageKit.SetSize(512, 512); // the dimensions of the image
imageKit.SetFormat(Image::Format::RGB); // the format tells HPS how to interpret the raw data
ImageKit imageKit = new ImageKit();
imageKit.SetData(image_data);
imageKit.SetSize(512, 512); // the dimensions of the image
imageKit.SetFormat(HPS.Image.Format.RGB); // the format tells HPS how to interpret the raw data

4.4.1 Saving a screenshot as an image

Visualize allows you to save a screenshot of your rendering result into an ImageKit. The data is initially preserved in RGB form, but the image kit is able to convert to other file formats if necessary. You are also able to simply inspect the data if you don't need to write it to a file. An example of this operation is as follows:

[snippet 4.4.1.a]
ImageKit myImageKit;
myWindowKey.ShowSnapshot(myImageKit);
// convert the image data to PNG
myImageKit.Convert(myImageKit, Image::Format::Png);
// get the PNG image into a buffer
ByteArray imageData;
myImageKit.ShowData(imageData);
$show_snapshot

Once you have the data in a buffer, you can write it to a file, inspect it, or do whatever you need to with it. Note that in order for this to work, you must have previously called WindowKey::Update at least once on the window key you wish to snapshot.