Brief Index      Full Index      I.M. Reference

Read_Metafile


Functions

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

Function Documentation

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

Reads a disk file of HOOPS information into a segment.

Parameters:
file - The name of the file o be read. If no filetype is included, ".hmf" is assumed.
segment - Segment in which the metafile data is placed.
options - A quoted string or a string variable containing a list of reading-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 end of a later program.

Metafiles can be read and written manually with Read_Metafile() and Write_Metafile() , or Set_Metafile() can be used to set up an automatic continuing relationship between a metafile and a segment. An explicit Read_Metafile() is useful when you want the actual metafile-reading 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 as follows:

[no] name =`string'

Specifies a disk file name to use, if file is blank. This option is provided for compatibility with Set_Metafile() . The default, if file is blank, if "name" is not given, and if Set_Metafile() has not specified a name, is to assume the metafile name is the same as the segment name.

[no] directory =`string'

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

[no] restore 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 "restore state" causes all the existing color names, texture definitions, fonts, alias names, and open segment names to be retrieved from the metafile, along with the contents of the segment. If a suboption is specified, only those specified will be restored. Available suboptions are: "aliases", "color names", "textures", "fonts" and "open items". Note: this information will be written out only if "save state" was also been turned on by the transmitting program. The save / restore state data should not be used for aliases such as ?picture, ?keyboard, and ?locater.

The default is to use the value specified by Set_Metafile() , otherwise it is "no restore state".

Segment will receive a Metafile attribute (see Set_Metafile() ) with the metafile name, the directory, a "read" option, and the "comment" and "original name", etc., options the file was written out with. Inner segments that receive full Metafile "read" attributes by virtue of the Read_Metafile() will be read in.

NOTES

I/O errors are reported back via the normal HOOPS error-handling mechanism.

RESTRICTIONS

See also:
Write_Metafile, Set_Metafile, Include_Segment, Begin_Contents_Search, Show_Existence.

Main Index
Brief Index      Full Index      I.M. Functions