Write_Metafile

Functions

void Write_Metafile (const char *segment, const char *file, const char *options)
 Writes the information in a segment out into a disk file. More...
 

Detailed Description

Function Documentation

◆ Write_Metafile()

void Write_Metafile ( const char *  segment,
const char *  file,
const char *  options 
)

Writes the information in a segment out into a disk file.

Parameters
segment- The segment with all its inner segments, which is to be written out.
file- The name of the file to be written. If no filetype is included, ".hmf" is assumed.
options- A quoted string or a string variable containing a list of writing-options.

DETAILS

"Metafiles" are the mechanism of generating and maintaining geometry and attributes in disk storage. A prime use of metafiles is to allow one program to transmit its graphics results to the input of a later program.
Metafiles can be read and written manually with Read_Metafile() and Write_Metafile() . An explicit Write_Metafile() is useful when you want the actual metafile-writing action to occur completely under your program control.
Options defines a list of details of how a metafile is to be read. Options is of the form "specification, specification,...", where each specification may be "item" or "item = value", or "no item". Extra blanks and uppercase versus lowercase do not matter. You can specify as few or as many items in the list as you want; the items not mentioned remain unaffected.
The possible options items are:

[no] directory ='string'

If file (or "name") does not include an directory specification, or if "name" is not specified at all, "directory" specifies a disk directory to use, in the syntax of the local operating system. If "directory" is not specified, the value specified by the HOOPS_METAFILES environment variable is used. If HOOPS_METAFILES is undefined, the current directory is used.

[no] comment ='string'

The "comment" will be included in the written file. If the "string" has any special characters in it, you can enclose it in single (') or double (") quotation marks.

[no] follow cross-references

When a "style" or "include" specification is encountered when writing a metafile, normally the name of the referenced segment, in another part of the segment tree, is written out. If "follow cross-references" is in effect, the referenced segment(s) will be written out too, in their entirety (but at most once per metafile). If a number of metafiles all reference and describe the same style or include segment, only the first one encountered will create the segment. Subsequent metafiles will skip ahead when they see that their referenced segment already exists.

If the scene refers to images outside of the segment tree from which the metafile is being written, this option should be used in combination with "save state = textures".

The default is "no follow cross-references".

[no] save state [=(options, options,...)]
Metafiles normally record the contents of a segment and do not record "system-wide" information such as color name definitions. Turning on "save state" causes all the existing color names, alias names, fonts, open segment names and textures to be dumped out to the metafile, along with the contents of the segment. If suboptions are specified, only those specified will be restored. Available suboptions are "aliases", "color names", "fonts", "open items" and "textures". Note: This information will be read back in only if "restore state" ( Read_Metafile() , on by default) ) has also been turned on by the receiving program.

A fairly complete system snapshot can be created by asking for "write, follow cross-references, use color names, save state" on "?Picture".

The default is to use the value set with Read_Metafile() , if any, otherwise it is "no save state".

[no] suppress LOD

Tells the HOOPS metafile generator to ignore LOD's in the scene.
[no] tristrips = [auto | force | supress]

Tells the HOOPS metafile generator to output tristrips. The default is "auto", in which case tristrips will be used if and only if the shells were originally inserted by tristrips. Using "force" will write tristrips that have been generated either by HOOPS or by user insertion, while "suppress" avoids tristip writing altogether.
[no] use color names
To be safe, the system normally writes out colors in terms of the raw color space coordinates. "Use color names" means it's OK to use the names of the colors—"red", "light green", etc.—for writing out color attributes. Use "save state", to also write out all the color name definitions.

The default is to use the value set with Read_Metafile() , if any, otherwise it is "no use color names".

As mentioned above, the contents of a segment, as sent to a metafile, normally include all of the segment's inner segments. However, there is one exception: a "metafiled" segment can have inner segments that have metafile attributes. In that case, what the system creates on disk is a metafile that just refers to the other metafiles.
The way the submetafiles work is that when the system is writing a metafile, and encounters a subsegment that has a metafile attribute, it writes out the subsegment's name and the metafile details, then skips over the rest of that subsegment. When the system is reading a metafile and encounters a subsegment with the metafile attribute, it sets the attribute and the "read" ends up recursing on itself.

NOTES

If you want to pack a number of branches of the segment tree into one metafile, one technique is to create a temporary segment, "include" all the segments you want into it, and turn on "follow cross-references". Then tell the system to write the whole temporary segment out.
"Driver" and "Driver Options" attributes are never included by the system in a metafile.
If you're using a renumbered-key (or a "User Value" attribute) to store a address pointer, and you write that to a metafile, the pointer value probably isn't going to be useful when the metafile is read back in. A better technique is to convert the information pointed to into a string, and store the string as a "User Option".
I/O errors are reported back via the normal HOOPS error-handling mechanism.

RESTRICTIONS

This function does not support geometry references. If your segment contains geometry references, we recommend that you use the .hsf format.

See also
Read_Metafile, Include_Segment, Begin_Color_Name_Search, Set_User_Options, Include_Segment, Define_Error_Handler.