======
Images
======

Images are defined in portfolios as a prerequisite to :doc:`defining a texture <0503_textures>`. 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``.

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_define_image.cpp
		   :start-after: //! [define_image]
		   :end-before: //! [define_image]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_define_image.cs
		   :start-after: //! [define_image]
		   :end-before: //! [define_image]

``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:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_define_image.cpp
		   :start-after: //! [manual_define_image]
		   :end-before: //! [manual_define_image]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_define_image.cs
		   :start-after: //! [manual_define_image]
		   :end-before: //! [manual_define_image]
		   

.. _screenshot:

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:

.. tabs::

	.. group-tab:: C++
	
		.. literalinclude:: ../../../internals/tests/docs/source/cpp/00700_save_screenshot.cpp
		   :start-after: //! [show_snapshot]
		   :end-before: //! [show_snapshot]
		   
	.. group-tab:: C#

		.. literalinclude:: ../../../internals/tests/docs/source/cs/00700_save_screenshot.cs
		   :start-after: //! [show_snapshot]
		   :end-before: //! [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 ``HPS::WindowKey::Update`` at least once on the window key you wish to snapshot.

