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_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)