Brief Index      Full Index      Events 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 metafile into a segment from a file.

Parameters:
file- The name of the file to be read. If no file type 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() . 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] 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 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 "no restore state".

Segment will receive a Metafile attribute 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, Include_Segment, Begin_Contents_Search, Show_Existence.

Brief Index      Full Index      Events Index      I.M. Reference