Commit 97ee1ad7 authored by Kenneth Moreland's avatar Kenneth Moreland
Browse files

Updated documentation.

parent e31fb7a7
......@@ -10,25 +10,29 @@
**
*****************************************************************************
Revision 2.2:
Added the icetCompositeImage function to allow IceT to operate on
pre-rendered images rather than rely on a rendering callback.
Revision 2.1:
Added Radix-k as a single-image strategy.
Added Radix-k as a single-image strategy.
Changed the collection method for single image compositing to use
the built-in gather functions of MPI. The old method had memory
problems with large numbers of processes and would probably be
inefficient anyway.
Changed the collection method for single image compositing to use
the built-in gather functions of MPI. The old method had memory
problems with large numbers of processes and would probably be
inefficient anyway.
Changed the single image compositing methods to work strictly with
compressed images. This prevents having to pad images with
background only to then test that same background later during
compression.
Changed the single image compositing methods to work strictly with
compressed images. This prevents having to pad images with
background only to then test that same background later during
compression.
Added interlace images option that provides a hint to the
compositing algorithms to try shuffling the pixels in images to
better load balance the active pixels during compositing.
Added interlace images option that provides a hint to the
compositing algorithms to try shuffling the pixels in images to
better load balance the active pixels during compositing.
Patch 1: Fixed compatibility issue with compiling against MPI
version 1. Fixed build issues for Windows.
Patch 1: Fixed compatibility issue with compiling against MPI
version 1. Fixed build issues for Windows.
Revision 2.0: A major restructuring of the IceT code comprising the
following changes:
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:53 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:53 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:53 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:53 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Thu Oct 9 15:41:59 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "icetCompositeImage" "3" "October 9, 2014" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetCompositeImage \-\- composites a pre\-rendered image\fP
.PP
.SH Synopsis
.PP
#include <IceT.h>
.PP
.TS H
l l l .
\fBIceTImage\fP \fBicetCompositeImage\fP(
const IceTVoid * \fIcolor_buffer\fP,
const IceTVoid * \fIdepth_buffer\fP,
const IceTInt * \fIvalid_pixels_viewport\fP,
const IceTDouble * \fIprojection_matrix\fP,
const IceTDouble * \fImodelview_matrix\fP,
const IceTFloat * \fIbackground_color\fP );
.TE
.PP
.SH Description
.PP
The \fBicetCompositeImage\fP
function takes image buffer data and
composites it to a single image. This function behaves similarly to
\fBicetDrawFrame\fP
except that instead of using callback functions to
render and retrieve image data, the images are pre\-rendered and passed
directly to \fBicetCompositeImage\fP\&.
Although it is more efficient to
allow \fBIceT \fPto determine rendering projections and use callbacks, it is
often more convenient for applications to integrate \fBIceT \fPas a separate
compositing step after the rendering.
.PP
Before \fBIceT \fPmay composite an image, the display needs to be defined
(using \fBicetAddTile\fP),
the buffer formats need to be specified
(using \fBicetSetColorFormat\fPand \fBicetSetDepthFormat\fP),and the composite
strategy must be set (using \fBicetStrategy\fP).
The single image
sub\-strategy may also optionally be set (using
\fBicetSingleImageStrategy\fP).
.PP
All process must call \fBicetCompositeImage\fP
for the operation to
complete on any process in a parallel job.
.PP
The \fIcolor_buffer\fP
and \fIdepth_buffer\fP
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 \fBicetAddTile\fP).
The global viewport is
stored in the \fBICET_GLOBAL_VIEWPORT\fP
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.
.PP
The format for \fIcolor_buffer\fP
is expected to be the same as what is
set with \fBicetSetColorFormat\fP\&.The following formats and their
interpretations with respect to \fIcolor_buffer\fP
are as follows.
.PP
.TP
\fBICET_IMAGE_COLOR_RGBA_UBYTE\fP
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.
.TP
\fBICET_IMAGE_COLOR_RGBA_FLOAT\fP
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.
.TP
\fBICET_IMAGE_COLOR_NONE\fP
No color values are stored in the
image.
.PP
Likewise, the format for \fIdepth_buffer\fP
is expected to be the same
as what is set with \fBicetSetDepthFormat\fP\&.The following formats and
their interpretations with respect to \fIdepth_buffer\fP
are as
follows.
.PP
.TP
\fBICET_IMAGE_DEPTH_FLOAT\fP
Each entry is in the range from
0.0 (near plane) to 1.0 (far plane) and is stored as a 32\-bit
float.
.TP
\fBICET_IMAGE_DEPTH_NONE\fP
No depth values are stored in the
image.
.PP
If the current format does not have a color or depth, then the respective
buffer argument should be set to NULL\&.
.PP
Care should be taken to make sure that the color and depth buffer formats
are consistent to the formats expected by \fBIceT \fP\&.Mismatched formats will
result in garbage images and possible memory faults.
.PP
Also note that when compositing with color blending
(\fBicetCompositeMode\fP
is set to
\fBICET_COMPOSITE_MODE_BLEND\fP),
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
\fIbackground_color\fP
as described below.
.PP
\fIvalid_pixels_viewport\fP
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 \fBIceT \fPcan take advantage of this
information. If the rendering system identifies such a region, it can be
specified with \fIvalid_pixels_viewport\fP\&.
.PP
Like all viewports in \fBIceT \fP,\fIvalid_pixels_viewport\fP
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
\fIcolor_buffer\fP
and \fIdepth_buffer\fP
arguments. Everything
outside of this rectangular region will be ignored. For example, if the
\fIvalid_pixels_viewport\fP
$<10, 20, 150, 100 >$is
given, then \fBicetCompositeImage\fP
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.
.PP
If \fIvalid_pixels_viewport\fP
is NULL,
then all pixels in the
input image are assumed to be valid.
.PP
\fIprojection_matrix\fP
and \fImodelview_matrix\fP
are optional
arguments that specify the projection that was used during rendering.
When applied to the geometry bounds information given with
\fBicetBoundingBox\fP
or \fBicetBoundingVertices\fP,
this provides
\fBIceT \fPwith 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, \fBIceT \fPmay 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.
.PP
The \fIbackground_color\fP
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\&.
.PP
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.
.PP
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
\fBICET_CORRECT_COLORED_BACKGROUND\fP
feature is enabled, this
background color is blended back into the final composited image.
.PP
.SH Return Value
.PP
On each .igdisplay processdisplay
process (as defined by
\fBicetAddTile\fP),
\fBicetCompositeImage\fP
returns the fully
composited image in an \fBIceTImage\fP
object. The contents of the
image are undefined for any non\-display process.
.PP
If the \fBICET_COMPOSITE_ONE_BUFFER\fP
option is on and both a color
and depth buffer is specified with \fBicetSetColorFormat\fPand
\fBicetSetDepthFormat\fP,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.
.PP
The returned image uses memory buffers that will be reclaimed the next
time \fBIceT \fPrenders or composites a frame. Do not use this image after
the next call to \fBicetCompositeImage\fP
(unless you have changed the
\fBIceT \fPcontext).
.PP
.SH Errors
.PP
.TP
\fBICET_INVALID_VALUE\fP
An argument is set to NULL
where data is required.
.TP
\fBICET_OUT_OF_MEMORY\fP
Not enough memory left to hold intermittent frame buffers and other
temporary data.
.PP
\fBicetDrawFrame\fP
may also indirectly raise an error if there is an
issue with the strategy or callback.
.PP
.SH Warnings
.PP
.TP
\fBICET_INVALID_VALUE\fP
An argument to \fBicetCompositeImage\fP
is inconsistent with the
current \fBIceT \fPstate.
.PP
.SH Bugs
.PP
The images provided must match the format expected by \fBIceT \fPor 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.
.PP
If compositing with color blending on, the image returned may have a
black background instead of the \fIbackground_color\fP
requested. This
can be corrected by blending the returned image over the desired
background. This will be done for you if the
\fBICET_CORRECT_COLORED_BACKGROUND\fP
feature is enabled.
.PP
.SH Copyright
Copyright (C)2014 Sandia Corporation
.PP
Under the terms of Contract DE\-AC04\-94AL85000 with Sandia Corporation, the
U.S. Government retains certain rights in this software.
.PP
This source code is released under the New BSD License.
.PP
.SH See Also
.PP
\fIicetAddTile\fP(3),
\fIicetBoundingBox\fP(3),
\fIicetBoundingVertices\fP(3),
\fIicetDrawCallback\fP(3),
\fIicetDrawFrame\fP(3),
\fIicetSetColorFormat\fP(3),
\fIicetSetDepthFormat\fP(3),
\fIicetSingleImageStrategy\fP(3),
\fIicetStrategy\fP(3)
.PP
.\" NOTE: This file is generated, DO NOT EDIT.
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Fri Sep 26 14:31:02 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -10,7 +10,7 @@
.fi
..
.TH "icetCompositeMode" "3" "August 9, 2010" "\fBIceT \fPReference" "\fBIceT \fPReference"
.TH "icetCompositeMode" "3" "September 26, 2014" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetCompositeMode \-\- set the type of operation used for compositing\fP
......@@ -91,11 +91,11 @@ None.
\fBicetCompositeMode\fP
will let you set a mode even if it is
incompatible with other current settings. Some settings will be checked
during a call to \fBicetDrawFrame\fP\&.
For example, if the image
format (specified with \fBicetSetColorFormat\fPand \fBicetSetDepthFormat\fP)does
not support the composite mode picked, you will get an error during the
call to \fBicetDrawFrame\fP\&.
during a call to \fBicetDrawFrame\fP
or \fBicetCompositeImage\fP\&.
For example, if the image format (specified with \fBicetSetColorFormat\fPand
\fBicetSetDepthFormat\fP)does not support the composite mode picked, you will
get an error during the call to \fBicetDrawFrame\fP\&.
.PP
Other incompatibilities are also not checked. For example, if the
composite mode is set to \fBICET_COMPOSITE_MODE_BLEND\fP,
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:53 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:53 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:53 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 17:14:18 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -10,7 +10,7 @@
.fi
..
.TH "icetDestroyContext" "3" "August 9, 2010" "\fBIceT \fPReference" "\fBIceT \fPReference"
.TH "icetDestroyContext" "3" "September 22, 2014" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetDestroyContext \-\- delete a context.\fP
......@@ -22,7 +22,7 @@
.PP
.TS H
l l l .
void \fBicetDestroyContext\fP( \fBIceTContext\fP \fIcontext\fP ;
void \fBicetDestroyContext\fP( \fBIceTContext\fP \fIcontext\fP );
.TE
.PP
.SH Description
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:53 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:53 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Fri Sep 26 14:31:02 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -10,7 +10,7 @@
.fi
..
.TH "icetEnable" "3" "July 11, 2011" "\fBIceT \fPReference" "\fBIceT \fPReference"
.TH "icetEnable" "3" "September 26, 2014" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetEnable\fP,\fBicetDisable\fP\-\- enable/disable an \fBIceT \fPfeature.
......@@ -44,17 +44,18 @@ are:
images partitions are always collected to display processes. When this
option is turned off, the strategy has the option of leaving images
partitioned among processes. Each process containing part of a tile\&'s
image will return the entire buffer from \fBicetDrawFrame\fP
or
\fBicetGLDrawFrame\fP
in an \fBIceTImage\fP
object. However, only
certain pixels will be valid. The state variables
\fBICET_VALID_PIXELS_TILE\fP,
image will return the entire buffer from \fBicetDrawFrame\fP,
\fBicetGLDrawFrame\fP,
or \fBicetCompositeImage\fP
in an
\fBIceTImage\fP
object. However, only certain pixels will be valid.
The state variables \fBICET_VALID_PIXELS_TILE\fP,
\fBICET_VALID_PIXELS_OFFSET\fP,
and \fBICET_VALID_PIXELS_NUM\fP
give which tile the pixels belong
to and what range of pixels are valid.
and
\fBICET_VALID_PIXELS_NUM\fP
give which tile the pixels belong to
and what range of pixels are valid.
.TP
\fBICET_COMPOSITE_ONE_BUFFER\fP
Turn this option on when
......@@ -72,10 +73,11 @@ cause the color to be blended back into the resulting images. This
flag is disabled by default.
.TP
\fBICET_FLOATING_VIEWPORT\fP
If enabled, the projection will
be shifted such that the geometry will be rendered in one shot whenever
possible, even if the geometry straddles up to four tiles. This flag
is enabled by default.
.igfloating viewport
If
enabled, the projection will be shifted such that the geometry will be
rendered in one shot whenever possible, even if the geometry straddles
up to four tiles. This flag is enabled by default.
.TP
\fBICET_INTERLACE_IMAGES\fP
If enabled, pixels in images
......@@ -95,6 +97,26 @@ enabled, you should call \fBicetCompositeOrder\fP
between each frame
to update the image order as camera angles change. This flag is
disabled by default.
.TP
\fBICET_RENDER_EMPTY_IMAGES\fP
If disabled, \fBIceT \fPwill never
invoke the drawing callback.igdrawing callback
if all geometry is
outside the clipping planes of the current projection. If enabled,
\fBIceT \fPwill still invoke the drawing callback \fIif\fP
the compositing
strategy has requested the tile. However, most compositing strategies
do not request images for all tiles. The floating viewport can also
consolidate up to four renderings into one. To ensure that the drawing
callback is invoked for all tiles on all processes, enable
\fBICET_RENDER_EMPTY_IMAGES\fP,
disable
\fBICET_FLOATING_VIEWPORT\fP,
and set the strategy (using
\fBicetStrategy\fP)
to \fBICET_STRATEGY_SEQUENTIAL\fP\&.
This flag
is disabled by default.
.PP
In addition, if you are using the \fbOpenGL \fPlayer (i.e., have called
\fBicetGLInitialize\fP),
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Mon Sep 22 15:51:53 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......
'\" t
.\" Manual page created with latex2man on Tue Jul 19 13:11:54 MDT 2011
.\" Manual page created with latex2man on Fri Sep 26 14:31:02 MDT 2014
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -10,7 +10,7 @@
.fi
..
.TH "icetDrawFrame" "3" "August 9, 2010" "\fBIceT \fPReference" "\fBIceT \fPReference"
.TH "icetDrawFrame" "3" "September 22, 2014" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetDrawFrame \-\- renders and composites a frame\fP
......@@ -68,16 +68,32 @@ to \fBicetDrawFrame\fP
and
then use the version passed to the drawing callback.
.PP
The \fIbackground_color\fP
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\&.
.PP
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 changed to transparent black during rendering to
prevent the background from being blended multiple times from different
renderings. If the \fBICET_CORRECT_COLORED_BACKGROUND\fP
feature is
enabled, this background color is blended back into the final composited
image.
.PP
.SH Return Value
.PP
On each .igdisplay processdisplay
process (as defined by
\fBicetAddTile\fP,
\fBicetAddTile\fP),
\fBicetDrawFrame\fP
returns an image of the fully
composited image. The contents of the image are undefined for any
non\-display process.
returns the fully composited
image in an \fBIceTImage\fP
object. The contents of the image are
undefined for any non\-display process.
.PP
If the \fBICET_COMPOSITE_ONE_BUFFER\fP
option is on and both a color
......@@ -90,18 +106,17 @@ might save some time by not transferring depth information at the latter
stage of compositing.