File Format Summary
Manual
Licensing
Basics
Intro
Data Order
Tags
Data Section
Version Section
Basic File Structure
Data Section Items
User Interact
Item deprecated
Reset View Item
deprecated
Grab Image Item
deprecated
Grab Frame Item
deprecated
Data Section Subsections
Image
Setup Section - More info
not implemented
Movie Setup
Section - More info not
implemented
Scene Section
- More info (over 10 tags)
View Section
- More info (over 30 tags)
Example
Basics
Intro
When building a file for this viewer, one thing to keep in mind is the
file is read sequentially. So, all "instructions" are carried out in the
order that they are specified, and are not looped (or anything else resembling
intelligence).
The file format for the viewer is divided into different sections. These
sections can have items in them or even other subsections. As an analogy,
the format of a viewer file can be compared to that of a directory structure.
Data Order
Different processors have different bit/byte orders, and this causes
problems when sharing files across systems. To counter this, all files
must start with an unsigned long of value DATA_ORDER_CHECK.
The value is defined in cuvtags.h, and the viewer will figure out
what byte order to use from how this is written (do not alter the value
in any way--just write an unsigned long of that value).
Tags
All sections and items are identified by unsigned chars, known
as tags. Besides starting a section with a tag, the section
also has to be terminated by another tag. The values of those unsigned char
tags are defined in cuvtags.h, which should be included in all file
creation programs. (* for programming purposes, an unsigned char by definition
is 8 bits = 1 byte => with a number range of 0 to 255; the ASCII
character set uses only about half the range).
Data Section
Everything within a viewer file is within the Data Section (except
data order)--the top-level directory in the analogy. The Data Section is
started by the tag called BEGIN_DATA, and is ended by either END_DATA_STAY
or END_DATA_EXIT. END_DATA_STAY will close the file, and leave
the viewer open for the user, while END_DATA_EXIT will close the viewer
when it is reached (useful for batching).
Version Section
Another section that is always in existence is the Version Section.
This section allows the viewer to deal with different versions, and it
also contains a human-readable string in it so the file format is easy to
determine when viewing the file as text. It is started by the BEGIN_VERSION
tag, and ended by the END_VERSION tag. The data between the two tags
is always VERSION_STRING.
Basic File Structure
Other sections and/or items occur between the end of the version, and
the end of the data. This is the space where all the 3D info goes.
Visually, the file should look like:
DATA_ORDER_CHECK
BEGIN_DATA
BEGIN_VERSION
VERSION_STRING
END_VERSION
(Other sections/items)
END_DATA_STAY or END_DATA_EXIT
Data Section Items
User Interact Item
(USER_INTERACT tag)
deprecated
This item will pause the reading of the file, and allow for user interaction.
This is useful when creating a movie, and the user needs to interactively
alter the environment, or just to peek at the scene to make sure your movie
is going as planned. It can also be used for a "slide show" to advance
to the next part of the file once the user has had enough time to view and
manipulate the scene. To let the viewer go back to reading the file, the
space bar must be hit by the user.
Reset View Item (RESET_VIEW
tag)
deprecated
This is the same as the 'r' key. It resets all the viewing variables
to the defaults (see the interactive reset view command for more info).
Grab Image Item (GRAB_IMAGE
tag)
deprecated
This is the same as the 'e' key. The current export options are used to create
an image on disk (see the interactive export image command for more info).
Grab Frame Item (GRAB_FRAME
tag)
deprecated
This is the same as the 'm' key. The current movie options are used to
add a frame to the current movie (see the interactive add a frame to the
movie command for more info).
Data Section Subsections
Image Setup
Section (BEGIN_IMG_SET and END_IMG_SET tags)
not implemented
This section is used to set the default image export options. More info
Movie Setup
Section (BEGIN_MOV_SET and END_MOV_SET tags)
not implemented
This section is used to set the default movie options. More info
Scene Section
(BEGIN_SCENE and END_SCENE tags)
This section is where all the 3D objects are defined. Over 10 tags defined:
More info
View Section (BEGIN_VIEW
and END_VIEW tags)
This section is where all the view's properties can be altered. Over
30 tags defined: More info
Example
The following example file creates a blue sphere, radius = 1 at the origin,
then goes to preset view 0 and lets the user interact with it. Following
that, the image is saved to disk, and a red sphere is saved to the disk
using the same environment. The bin palette information corresponding
to the lowest and highest values on the palette are written, in units of
Celcius. The file is then closed, and the program is instructed to remain
open.
BEGIN_DATA
BEGIN_VERSION
VERSION_STRING
END_VERSION
BEGIN_SCENE
SSPHERE
unsigned char = 0x01 (filled)
float [3] = {0.0, 0.0, 0.0} (position)
float = 1.0 (radius)
float [3] = {0.0, 0.0, 1.0} (color)
END_SCENE
BEGIN_VIEW
VPRESET_VIEW
unsigned char = 0x00 (preset view 0)
VBIN_PAL_MIN_MAX
float = 1.31
float = 253.22
VBIN_PAL_TYPE
"Celcius\0"
END_VIEW
USER_INTERACT
GRAB_IMAGE
BEGIN_SCENE
SSPHERE
unsigned char = 0x01 (filled)
float [3] = {0.0, 0.0, 0.0} (position)
float = 1.0 (radius)
float [3] = {1.0, 0.0, 0.0} (color)
END_SCENE
GRAB_IMAGE
END_DATA_STAY