Ubuntu Manpage: icetCompositeImage -- composites a pre-rendered image

Provided by: paraview_5.11.2+dfsg-6build5_amd64

NAME

       icetCompositeImage -- composites a pre-rendered image

Synopsis

       #include <IceT.h>

       IceTImage icetCompositeImage(
                                       const IceTVoid *     color_buffer,
                                       const IceTVoid *     depth_buffer,
                                       const IceTInt *      valid_pixels_viewport,
                                       const IceTDouble *   projection_matrix,
                                       const IceTDouble *   modelview_matrix,
                                       const IceTFloat *    background_color  );

Description

The icetCompositeImage function takes image buffer data and composites it to a single image. This
function behaves similarly to icetDrawFrame except that instead of using callback functions to render and
retrieve image data, the images are pre-rendered and passed directly to icetCompositeImage. Although it
is more efficient to allow IceT to determine rendering projections and use callbacks, it is often more
convenient for applications to integrate IceT as a separate compositing step after the rendering.

Before IceT may composite an image, the display needs to be defined (using icetAddTile), the buffer
formats need to be specified (using icetSetColorFormatand icetSetDepthFormat),and the composite strategy
must be set (using icetStrategy). The single image sub-strategy may also optionally be set (using
icetSingleImageStrategy).

All process must call icetCompositeImage for the operation to complete on any process in a parallel job.

The color_buffer and depth_buffer arguments point to memory buffers that contain the image data. The
image data is always stored in densely packed arrays in row-major order (a.k.a. x-major order or by
scan-lines). The first horizontal scan-line is at the bottom of the image with subsequent scan-lines
moving up. The size of each image buffer is expected to be the width and the height of the global
viewport (which is set indirectly with icetAddTile). The global viewport is stored in the
ICET_GLOBAL_VIEWPORT state variable. If only one tile is specified, then the width and height of the
global viewport will be the same as this one tile.

The format for color_buffer is expected to be the same as what is set with icetSetColorFormat.The
following formats and their interpretations with respect to color_buffer are as follows.

ICET_IMAGE_COLOR_RGBA_UBYTE
Each entry is an RGBA color tuple. Each component is valued in the range from 0 to 255 and is
stored as an 8-bit integer. The buffer will always be allocated on memory boundaries such that
each color value can be treated as a single 32-bit integer.

ICET_IMAGE_COLOR_RGBA_FLOAT
Each entry is an RGBA color tuple. Each component is in the range from 0.0 to 1.0 and is stored
as a 32-bit float.

ICET_IMAGE_COLOR_RGB_FLOAT
Each entry is an RGB color triple. Each component is in the range from 0.0 to 1.0 and is stored
as a 32-bit float. Note that there is no alpha channel, so the color blending composite mode will
not work with this color format.

ICET_IMAGE_COLOR_NONE
No color values are stored in the image.

Likewise, the format for depth_buffer is expected to be the same as what is set with
icetSetDepthFormat.The following formats and their interpretations with respect to depth_buffer are as
follows.

ICET_IMAGE_DEPTH_FLOAT
Each entry is in the range from 0.0 (near plane) to 1.0 (far plane) and is stored as a 32-bit
float.

ICET_IMAGE_DEPTH_NONE
No depth values are stored in the image.

If the current format does not have a color or depth, then the respective buffer argument should be set
to NULL.

Care should be taken to make sure that the color and depth buffer formats are consistent to the formats
expected by IceT .Mismatched formats will result in garbage images and possible memory faults.

Also note that when compositing with color blending (icetCompositeMode is set to
ICET_COMPOSITE_MODE_BLEND), the color buffer must be rendered with a black background in order for the
composite to complete correctly. A colored background can later be added using the background_color as
described below.

valid_pixels_viewport is an optional argument that makes it possible to specify a subset of pixels that
are valid. In parallel rendering it is common for a single process to render geometry in only a small
portion of the image, and IceT can take advantage of this information. If the rendering system identifies
such a region, it can be specified with valid_pixels_viewport.

Like all viewports in IceT ,valid_pixels_viewport is an array of 4 integers in the form $<x, y, width,
height >$.This viewport is given in relation to the image passed in the color_buffer and depth_buffer
arguments. Everything outside of this rectangular region will be ignored. For example, if the
valid_pixels_viewport $<10, 20, 150, 100 >$is given, then icetCompositeImage will ignore all pixels in
the bottom 10 rows, the left 20 columns, anything above the $160^th$ (10+150) row, and anything to the
right of the $120^th$ (20+100) column.

If valid_pixels_viewport is NULL, then all pixels in the input image are assumed to be valid.

projection_matrix and modelview_matrix are optional arguments that specify the projection that was used
during rendering. When applied to the geometry bounds information given with icetBoundingBox or
icetBoundingVertices, this provides IceT with further information on local image projections. If the
given matrices are not the same used in the rendering or the given bounds do not contain the geometry,
IceT may clip the geometry in surprising ways. If these arguments are set to NULL, then geometry
projection will not be considered when determining what parts of images are valid.

The background_color argument specifies the desired background color for the image. It is given as an
array of 4 floating point values specifying, in order, the red, green, blue, and alpha channels of the
color in the range from 0.0 to 1.0.

When rendering using a depth buffer, the background color is used to fill in empty regions of images.
When rendering using color blending, the background color is used to correct colored backgrounds.

As stated previously, color blended compositing only works correctly if the images are rendered with a
clear black background. Otherwise the background color will be added multiple times by each process that
contains geometry in that pixel. If the ICET_CORRECT_COLORED_BACKGROUND feature is enabled, this
background color is blended back into the final composited image.

Return Value

       On  each  .igdisplay  processdisplay  process (as defined by icetAddTile), icetCompositeImage returns the
       fully composited image in an  IceTImage  object.  The  contents  of  the  image  are  undefined  for  any
       non-display process.

       If  the  ICET_COMPOSITE_ONE_BUFFER  option  is  on  and  both  a color and depth buffer is specified with
       icetSetColorFormatand icetSetDepthFormat,then the returned image might be missing the depth  buffer.  The
       rational  behind  this  option  is  that  often  both the color and depth buffer is necessary in order to
       composite the color buffer, but the composited depth buffer is not needed. In this case, the  compositing
       might save some time by not transferring depth information at the latter stage of compositing.

       The  returned image uses memory buffers that will be reclaimed the next time IceT renders or composites a
       frame. Do not use this image after the next call to icetCompositeImage (unless you have changed the  IceT
       context).

Errors

       ICET_INVALID_VALUE
               An argument is set to NULL where data is required.

       ICET_OUT_OF_MEMORY
               Not enough memory left to hold intermittent frame buffers and other temporary data.

       icetDrawFrame may also indirectly raise an error if there is an issue with the strategy or callback.

Warnings

       ICET_INVALID_VALUE
               An argument to icetCompositeImage is inconsistent with the current IceT state.

Bugs

       The  images provided must match the format expected by IceT or else unpredictable behavior may occur. The
       images must also be carefully rendered to follow the provided viewport and  projections.  Images  that  a
       color blended must be rendered with a black background and rendered with the correct alpha value.

       If  compositing  with  color  blending  on, the image returned may have a black background instead of the
       background_color requested. This can be corrected  by  blending  the  returned  image  over  the  desired
       background. This will be done for you if the ICET_CORRECT_COLORED_BACKGROUND feature is enabled.

Copyright

       Copyright (C)2014 Sandia Corporation

       Under  the  terms  of  Contract  DE-AC04-94AL85000  with  Sandia Corporation, the U.S. Government retains
       certain rights in this software.

       This source code is released under the New BSD License.