Functions | |
void | Open_Segment (const char *segment) |
HC_KEY | KOpen_Segment (const char *segment) |
void | Open_Segment_By_Key (HC_KEY key) |
void Open_Segment | ( | const char * | segment | ) |
Readies a segment to receive drawing commands. (Also useful when several attributes all need changing at once.).
segment | - Name of the segment. |
If you do not need to refer back to a segment by name once it's created, you can omit naming it. To do this, pass a blank (or zero-length) string as the argument to Open_Segment() . The system will go ahead and open a new unnamed segment within the currently open segment, and you can work within it as usual. Once you close the unnamed segment back up, you will only be able to refer to it by key or by wildcard name---each and every blank-name Open creates an independent new segment.
If there is no previously open segment, you must provide a name and the name must start at the root ("/") or at one of the predefined main directories "?Picture", "?Style Library", or "?Include Library". Once this segment is open, it'll be used as a "default directory" for all future name expanding until it is closed once again.
You can open and close a segment as many times as you please, and you may do "Opens" even inside of other "Opens". In fact, you might commonly do them inside of other ones, as a natural way of walking up and down the segment tree.
If you ask for a segment that has never been opened before---a segment that does not exist---a segment and all necessary containing segments are created. Depending on what you ask for, the Open_Segment() might result in going down several layers at once or going off to a completely different part of the segment tree. This is fine. The Close_Segment() , when it happens, will get you all the way back to what was previously open.
One complication you should be aware of: if the first call in a HOOPS program is a Set or an Insert, and (of course) no segment is open yet, the system assumes you don't want to use segments at all and automatically opens a default display segment in streaming mode. The system is then said to be in "non-segmented" mode, although segments can actually still be created elsewhere in the tree.
The limit on the length of segment names is large (on the order of 2^15---32,000---characters.) Extremely long names may slow down execution a trifle.
There is no need to close open segments before opening other segments, requesting input and updating the screen, or doing any operation. Your program should make sure that there is a Close_Segment() to match every Open.
Segments are normally opened and closed by name. Open_Segment_By_Key() routine is provided in case it's more convenient for your program to find its way around by number rather than by name. Opening by key is also the only way provided to reenter a "no-name" segment. Keys are always chosen by the system; in this case they are returned by an initial call to KOpen_Segment() or KCreate_Segment() .
If you do have to refer to a "no-name" segment by key later on, you can either use Open_Segment_By_Key() , or you can code the key value into a string of the form "@hex-value", and use that string as a substitute for the usual segment name.
ISO Latin-1 characters can be used in segment names. Please refer to Table 4.1.
BAD:
Open_Geometry (key) Open_Face (number) Close_Face (number) Open_Segment ("temp") Close_Segment () Close_Geometry ()
GOOD:
Open_Geometry (key) Open_Face (number) Close_Face (number) Open_Segment ("?driver/sbx/unix:0.0" Close_Segment () Close_Geometry ()
HC_KEY KOpen_Segment | ( | const char * | segment | ) |
Similar to Open_Segment(), but returns an HC_KEY to the object.
segment | - Name of the segment. |
void Open_Segment_By_Key | ( | HC_KEY | key | ) |
Similar to Open_Segment(), but operates on an object referenced by an HC_KEY.
key | - Unique simple identifier for this segment. Returned to caller in KOpen_Segment() , accepted as an argument in Open_Segment_By_Key() . |