Provided by: paraview_5.11.2+dfsg-6build5_amd64 bug

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.

See Also

       icetAddTile(3),    icetBoundingBox(3),    icetBoundingVertices(3),    icetDrawCallback(3),
       icetDrawFrame(3),              icetSetColorFormat(3),               icetSetDepthFormat(3),
       icetSingleImageStrategy(3), icetStrategy(3)

IceT Reference                           October  9, 2014                   icetCompositeImage(3)