Commit 0af692c2 authored by Kenneth Moreland's avatar Kenneth Moreland
Browse files

Update documentation on ICET_IMAGE_COLOR_RGB_FLOAT

Also removed whitespace at the end of generated manpages.
parent a70bb7f1
......@@ -14,6 +14,8 @@ Revision 2.2:
Added the icetCompositeImage function to allow IceT to operate on
pre-rendered images rather than rely on a rendering callback.
Added the ICET_IMAGE_COLOR_RGB_FLOAT color format.
Revision 2.1:
Added Radix-k as a single-image strategy.
......
'\" t
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" Manual page created with latex2man on Tue Mar 13 15:04:17 MDT 2018
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -32,53 +32,53 @@ int \fBicetAddTile\fP( IceTInt \fIx\fP,
.SH Description
.PP
Adds a tile to the tiled display. Every process, whether actually
displaying a tile or not, must declare the tiles in the display and which
Adds a tile to the tiled display. Every process, whether actually
displaying a tile or not, must declare the tiles in the display and which
processes drive them with \fBicetResetTiles\fP
and \fBicetAddTile\fP\&.
Thus, each process calls \fBicetAddTile\fP
once for each tile in the
display, and all processes must declare them in the same order.
once for each tile in the
display, and all processes must declare them in the same order.
.PP
The parameters \fIx\fP,
\fIy\fP,
\fIwidth\fP,
and \fIheight\fP
define
the tile\&'s viewport in the logical global display much in the same way
define
the tile\&'s viewport in the logical global display much in the same way
\fBglViewport\fP
declares a region in a physical display in
\fbOpenGL \fP\&.\fBIceT \fPplaces no limits on the extents of the logical global
declares a region in a physical display in
\fbOpenGL \fP\&.\fBIceT \fPplaces no limits on the extents of the logical global
display. That is, there are no limits on the values of \fIx\fP
and
and
\fIy\fP\&.
They can extend as far as they want in both the positive and
negative directions.
They can extend as far as they want in both the positive and
negative directions.
.PP
\fBIceT \fPwill project its images onto the region of the logical global
display that just covers all of the tiles. Therefore, shifting all the
tiles in the logical global display by the same amount will have no real
overall effect.
\fBIceT \fPwill project its images onto the region of the logical global
display that just covers all of the tiles. Therefore, shifting all the
tiles in the logical global display by the same amount will have no real
overall effect.
.PP
The \fIdisplay_rank\fP
parameter identifies the rank of the process
that will be displaying the given tile. It is assumed that the output of
the rendering window of the given process is projected onto the space in
parameter identifies the rank of the process
that will be displaying the given tile. It is assumed that the output of
the rendering window of the given process is projected onto the space in
a tiled display given by \fIx\fP,
\fIy\fP,
\fIwidth\fP,
and
and
\fIheight\fP\&.
Each tile must have a valid rank (between 0 and
Each tile must have a valid rank (between 0 and
$\fBICET_NUM_PROCESSES\fP
\- 1$). Furthermore, no process may be
displaying more than one tile.
\- 1$). Furthermore, no process may be
displaying more than one tile.
.PP
.SH Return Value
.PP
Returns the index of the tile created or \-1 if the tile could not be
created.
Returns the index of the tile created or \-1 if the tile could not be
created.
.PP
.SH Errors
......@@ -87,32 +87,32 @@ created.
\fBICET_INVALID_VALUE\fP
Raised if \fIdisplay_rank\fP
is not a valid process rank, if \fIdisplay_rank\fP
is already
is already
assigned to another tile, or if \fIwidth\fP
or \fIheight\fP
is
smaller than 1. If this error is raised, nothing is done and \-1 is
returned.
is
smaller than 1. If this error is raised, nothing is done and \-1 is
returned.
.PP
.SH Warnings
.PP
None.
None.
.PP
.SH Bugs
.PP
All processes must specify the same tiles in the same order. \fBIceT \fP
will assume this even though it is not explicitly detected or enforced.
will assume this even though it is not explicitly detected or enforced.
.PP
.SH Copyright
Copyright (C)2003 Sandia Corporation
Copyright (C)2003 Sandia Corporation
.PP
Under the terms of Contract DE\-AC04\-94AL85000 with Sandia Corporation, the
U.S. Government retains certain rights in this software.
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.
This source code is released under the New BSD License.
.PP
.SH See Also
......
'\" t
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" Manual page created with latex2man on Tue Mar 13 15:04:17 MDT 2018
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -13,7 +13,7 @@
.TH "icetBoundingBox" "3" "August 9, 2010" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetBoundingBoxd\fP,\fBicetBoundingBoxf\fP \-\- set bounds of geometry
\fBicetBoundingBoxd\fP,\fBicetBoundingBoxf\fP \-\- set bounds of geometry
.PP
.SH Synopsis
......@@ -43,38 +43,38 @@ void \fBicetBoundingBoxf\fP( IceTFloat \fIx_min\fP,
.SH Description
.PP
Establishes the bounds of the geometry as contained in an axis\-aligned
box with the given extents.
Establishes the bounds of the geometry as contained in an axis\-aligned
box with the given extents.
.PP
\fBicetBoundingBoxd\fPand \fBicetBoundingBoxf\fP are really just convience
functions. They create an array of the 8 corner vertices and set the
\fBicetBoundingBoxd\fPand \fBicetBoundingBoxf\fP are really just convience
functions. They create an array of the 8 corner vertices and set the
bounding vertices appropriately. See \fBicetBoundingVertices\fP
for
more information.
for
more information.
.PP
.SH Errors
.PP
None.
None.
.PP
.SH Warnings
.PP
None.
None.
.PP
.SH Bugs
.PP
None known.
None known.
.PP
.SH Copyright
Copyright (C)2003 Sandia Corporation
Copyright (C)2003 Sandia Corporation
.PP
Under the terms of Contract DE\-AC04\-94AL85000 with Sandia Corporation, the
U.S. Government retains certain rights in this software.
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.
This source code is released under the New BSD License.
.PP
.SH See Also
......
'\" t
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" Manual page created with latex2man on Tue Mar 13 15:04:17 MDT 2018
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -13,7 +13,7 @@
.TH "icetBoundingBox" "3" "August 9, 2010" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetBoundingBoxd\fP,\fBicetBoundingBoxf\fP \-\- set bounds of geometry
\fBicetBoundingBoxd\fP,\fBicetBoundingBoxf\fP \-\- set bounds of geometry
.PP
.SH Synopsis
......@@ -43,38 +43,38 @@ void \fBicetBoundingBoxf\fP( IceTFloat \fIx_min\fP,
.SH Description
.PP
Establishes the bounds of the geometry as contained in an axis\-aligned
box with the given extents.
Establishes the bounds of the geometry as contained in an axis\-aligned
box with the given extents.
.PP
\fBicetBoundingBoxd\fPand \fBicetBoundingBoxf\fP are really just convience
functions. They create an array of the 8 corner vertices and set the
\fBicetBoundingBoxd\fPand \fBicetBoundingBoxf\fP are really just convience
functions. They create an array of the 8 corner vertices and set the
bounding vertices appropriately. See \fBicetBoundingVertices\fP
for
more information.
for
more information.
.PP
.SH Errors
.PP
None.
None.
.PP
.SH Warnings
.PP
None.
None.
.PP
.SH Bugs
.PP
None known.
None known.
.PP
.SH Copyright
Copyright (C)2003 Sandia Corporation
Copyright (C)2003 Sandia Corporation
.PP
Under the terms of Contract DE\-AC04\-94AL85000 with Sandia Corporation, the
U.S. Government retains certain rights in this software.
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.
This source code is released under the New BSD License.
.PP
.SH See Also
......
'\" t
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" Manual page created with latex2man on Tue Mar 13 15:04:17 MDT 2018
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -13,7 +13,7 @@
.TH "icetBoundingBox" "3" "August 9, 2010" "\fBIceT \fPReference" "\fBIceT \fPReference"
.SH NAME
\fBicetBoundingBoxd\fP,\fBicetBoundingBoxf\fP \-\- set bounds of geometry
\fBicetBoundingBoxd\fP,\fBicetBoundingBoxf\fP \-\- set bounds of geometry
.PP
.SH Synopsis
......@@ -43,38 +43,38 @@ void \fBicetBoundingBoxf\fP( IceTFloat \fIx_min\fP,
.SH Description
.PP
Establishes the bounds of the geometry as contained in an axis\-aligned
box with the given extents.
Establishes the bounds of the geometry as contained in an axis\-aligned
box with the given extents.
.PP
\fBicetBoundingBoxd\fPand \fBicetBoundingBoxf\fP are really just convience
functions. They create an array of the 8 corner vertices and set the
\fBicetBoundingBoxd\fPand \fBicetBoundingBoxf\fP are really just convience
functions. They create an array of the 8 corner vertices and set the
bounding vertices appropriately. See \fBicetBoundingVertices\fP
for
more information.
for
more information.
.PP
.SH Errors
.PP
None.
None.
.PP
.SH Warnings
.PP
None.
None.
.PP
.SH Bugs
.PP
None known.
None known.
.PP
.SH Copyright
Copyright (C)2003 Sandia Corporation
Copyright (C)2003 Sandia Corporation
.PP
Under the terms of Contract DE\-AC04\-94AL85000 with Sandia Corporation, the
U.S. Government retains certain rights in this software.
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.
This source code is released under the New BSD License.
.PP
.SH See Also
......
'\" t
.\" Manual page created with latex2man on Mon Sep 22 15:51:52 MDT 2014
.\" Manual page created with latex2man on Tue Mar 13 15:04:17 MDT 2018
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -33,59 +33,59 @@ void \fBicetBoundingVertices\fP( IceTInt \fIsize\fP,
.PP
\fBicetBoundingVertices\fP
is used to tell \fBIceT \fPwhat the bounds of the
is used to tell \fBIceT \fPwhat the bounds of the
geometry drawn by the callback registered with \fBicetDrawCallback\fP
or \fBicetGLDrawCallback\fP
are. The bounds are assumed to be the
convex hull of the vertices given. The user should take care to make
sure that the drawn geometry actually does fit within the convex hull, or
the data may be culled in unexpected ways. \fBIceT \fPruns most efficiently
when the bounds given are tight (match the actual volume of the data
well) and when the number of vertices given is minimal.
are. The bounds are assumed to be the
convex hull of the vertices given. The user should take care to make
sure that the drawn geometry actually does fit within the convex hull, or
the data may be culled in unexpected ways. \fBIceT \fPruns most efficiently
when the bounds given are tight (match the actual volume of the data
well) and when the number of vertices given is minimal.
.PP
The \fIsize\fP
parameter specifies the number of coordinates given for
each vertex. Coordinates are given in X\-Y\-Z\-W order. Any Y or Z
parameter specifies the number of coordinates given for
each vertex. Coordinates are given in X\-Y\-Z\-W order. Any Y or Z
coordinate not given (because \fIsize\fP
is less than 3) is assumed to
is less than 3) is assumed to
be 0.0, and any W coordinate not given (because \fIsize\fP
is less
than 4) is assumed to be 1.0\&.
is less
than 4) is assumed to be 1.0\&.
.PP
The \fItype\fP
parameter specifies in what data type the coordinates are
parameter specifies in what data type the coordinates are
given. Valid \fItype\fPs
are \fBICET_SHORT\fP,
\fBICET_INT\fP,
\fBICET_FLOAT\fP,
and \fBICET_DOUBLE\fP,
which correspond to types
which correspond to types
IceTShort,
IceTInt,
IceTFloat,
and
and
IceTDouble,
respectively.
respectively.
.PP
The \fIstride\fP
parameter specifies the offset between consecutive
parameter specifies the offset between consecutive
vertices in bytes. If \fIstride\fP
is 0, the array is assumed to be
tightly packed.
is 0, the array is assumed to be
tightly packed.
.PP
The \fIcount\fP
parameter specifies the number of vertices to set.
parameter specifies the number of vertices to set.
.PP
The \fIpointer\fP
parameter is an array of vertices with the first
vertex starting at the first byte.
parameter is an array of vertices with the first
vertex starting at the first byte.
.PP
If data replication is being used, each process in a data replication
group should register the same bounding vertices that encompass the
entire geometry. By default there is no data replication, so unless you
If data replication is being used, each process in a data replication
group should register the same bounding vertices that encompass the
entire geometry. By default there is no data replication, so unless you
call \fBicetDataReplicationGroup\fP,
all process can have their own
bounds.
all process can have their own
bounds.
.PP
.SH Errors
......@@ -101,21 +101,21 @@ or \fBICET_DOUBLE\fP\&.
.SH Warnings
.PP
None.
None.
.PP
.SH Bugs
.PP
None known.
None known.
.PP
.SH Copyright
Copyright (C)2003 Sandia Corporation
Copyright (C)2003 Sandia Corporation
.PP
Under the terms of Contract DE\-AC04\-94AL85000 with Sandia Corporation, the
U.S. Government retains certain rights in this software.
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.
This source code is released under the New BSD License.
.PP
.SH See Also
......
'\" t
.\" Manual page created with latex2man on Thu Oct 9 15:41:59 MDT 2014
.\" Manual page created with latex2man on Tue Mar 13 15:04:18 MDT 2018
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
......@@ -35,193 +35,199 @@ l l l .
.PP
The \fBicetCompositeImage\fP
function takes image buffer data and
composites it to a single image. This function behaves similarly to
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
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.
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
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
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
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.
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
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
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.
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
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.
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.
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.
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_RGB_FLOAT\fP
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.
.TP
\fBICET_IMAGE_COLOR_NONE\fP
No color values are stored in the
image.
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
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.
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.
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.
No depth values are stored in the
image.
.PP
If the current format does not have a color or depth, then the respective
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.
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
Also note that when compositing with color blending
(\fBicetCompositeMode\fP
is set to
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
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.
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
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 >$.Th