#########################
Loading and Saving Images
#########################


*********
Image I/O
*********

Images can be loaded (or saved) either from a RED file or from a common image file format like JPEG, PNG or HDR:

.. include:: /tasks/ta_ca/ta_ca_image/tk_loading_and_saving_image_to_red_file.rst

.. include:: /tasks/ta_ca/ta_ca_image/tk_loading_and_saving_image_to_file.rst

What differs is that in a RED file, the image is saved with its whole configuration including targets, filtering information. Moreover, in a RED file, an image can be of any HOOPS Luminate supported types (Composite, cube, 3d...) and pixel formats while common image file formats only support 2d images in a reduced set of pixel formats.

***********************
Supported Image Formats
***********************

The supported common image file formats are: 

    * JPG for RGB images
    * PNG for RGB/RGBA images 
    * HDR for floating point pixel formats

The JPEG format is known for its very good compression/quality ratio and can be used any time the size of the output image matters. However, due to its specifications, the format doesn't support pixel formats other than ``RED::FMT_RGB``. Any other pixel format will be converted by the API following the table given in ``RED::ImageTools::Save``. 

.. note:: 
    
    Do not forget that JPEG is a lossy compression format. Don't rely on it to preserve all the details of your images.

The PNG format provides lossless compression: image quality is preserved at the price of bigger files. Pixel formats with alpha channels are supported. As for JPEG, input pixels may be converted prior to saving following the conversion rules in ``RED::ImageTools::Save``.

Finally HDR (for High Dynamic Range) is a lossless compressed image format which can handle pixel formats in floating point precision. It lets you save on disk outputs from the HOOPS Luminate ray-tracer (which are high dynamic range images) without loosing quality due to quantification. It also becomes very useful when it comes to load environment photographs which serve as light textures for hemispherical lighting (see http://www.hdrlabs.com for examples of how to use HDR images to lit your 3d scenes).

******************************
When to use the Local Storage?
******************************

Each HOOPS Luminate image comes with a local storage which can be used to store a local copy of the image content. Because images are synchronously processed in HOOPS Luminate, you can't get access or modify image contents while a rendering operation is being processed (:doc:`/book/subjects/bk_ba/bk_ba_tm/bk_ba_modifying_images_during_a_draw`). Hence, if you create images on-the-fly by loading them from a file for example, you must guarantee that all the image operations take place between two rendering calls. 

Local storages were introduced to avoid such situations where the rendering is interrupted during an image load or an image edition. It serves as an intermediate location between the image source and the renderer memory where content processing can occur asynchronously from the rendering operations. This enables you to load data in parallel of a rendering operation without needing to interrupt it.

When the source is a RED file, the default storage used is the renderer memory (can be either graphics card or main memory). To change that, you need to set the local images flag in the file policy (``RED::StreamingPolicy::SetLocalImages``) to true.

When the source is a common image file format, the destination storage needs to be specified in the call (see ``RED::ImageTools::Load``).

Whatever the source you use, contents loaded in local storages are not available to the renderer until they've been explicitly uploaded (see **Managing Image Pixels** in the doc :doc:`/book/subjects/bk_im/bk_im_manipulating_images`).

.. note:: 
    
    If all your image edition operations occur before the first call to the renderer, you don't need to worry about the local storage and can send directly the image contents to their default storages.