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 HPS::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 HPS::IOException.

try
{
HPS::ImageKit imageKit = HPS::Image::File::Import(filename, iok);
HPS::ImageDefinition imageDefinition = myPortfolio.DefineImage("my_image", imageKit);
}
catch (HPS::IOException ioe)
{
const char* problem = ioe.what(); // shows cause of the exception
}
try
{
HPS.ImageKit imageKit = HPS.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
}



HPS::Portfolio::DefineImage expects an HPS::ImageKit object as a parameter, which is returned by HPS::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 HPS::ImageKit manually. When defining images that are loaded without the use of HPS::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:

HPS::ImageKit imageKit;
imageKit.SetData(byteArray);
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
HPS.ImageKit imageKit = new HPS.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



Saving a screenshot as an image

Visualize allows you to save a screenshot of your rendering result into an HPS::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:

HPS::ImageKit myImageKit;
myWindowKey.ShowSnapshot(myImageKit);
// convert the image data to PNG
myImageKit.Convert(myImageKit, HPS::Image::Format::Png);
// get the PNG image into a buffer
ByteArray imageData;
myImageKit.ShowData(imageData);
HPS.ImageKit myImageKit = new HPS.ImageKit();
myWindowKey.ShowSnapshot(out myImageKit);
// convert the image data to PNG
myImageKit.Convert(myImageKit, HPS.Image.Format.Png);
// get the PNG image into a buffer
Byte[] imageData;
myImageKit.ShowData(out imageData);



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 HPS::WindowKey::Update at least once on the window key you wish to snapshot.