Open_Segment

Functions

HC_KEY Open_Segment (const char *segment)
 Readies a segment to receive drawing commands. (Also useful when several attributes all need changing at once.) More...
 
HC_KEY Open_Segment_By_Key (HC_KEY key)
 Similar to Open_Segment(), but operates on an object referenced by an HC_KEY. More...
 
HC_KEY Open_Segment_Key_By_Key (HC_KEY parent_segment, char const *child_segment_name)
 Similar to Open_Segment(), but opens a child segment under parent_segment instead of the currently opened segment. More...
 

Detailed Description

Function Documentation

◆ Open_Segment()

HC_KEY Open_Segment ( const char *  segment)

Readies a segment to receive drawing commands. (Also useful when several attributes all need changing at once.)

Parameters
segment- Name of the segment.
Returns
The key to the opened segment.

DETAILS

The name provided must be a simple name, path name, or blank string—no wildcards are allowed in this context. It can be whatever string you please, as long as you enclose special characters in single or double quotes, e.g., "?picture/hpgl/'c:\hoops\hpgl.out'". If the segment did not previously exist, it is created. If it did, it is made ready for additions and changes.
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.

NOTES

A segment that is Open (at any level) cannot be deleted until it is closed.
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 Open_Segment() or Create_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.

Legal Characters for Segment Names:

The normal useful set of characters for segment names consists of letters, numbers, space, and some punctuation (mostly characters commonly used in file specifications, with the exception of the / used in Unix-style directory paths):

    A-Z a-z 0-9 $_#&+-.:[\]
    ISO Latin-1 characters from 0xC0 - 0xFF *except* non-alphabetic characters at 0xD7 and 0xF7

Note that by default, uppercase characters are converted to their lowercase version, leading and trailing spaces are trimmed. Quotes (single, double, or back) may not appear individually, and certain characters are not normally considered valid as part of a segment name as they have special meaning to segment path resolution:

    /^*%!@,<>{}()?

On top of all that, any ISO Latin-1 character may be used if the segment name is quoted, using single, double, or back quotes. Note that inclusion of a quote character of the same type is handled by doubling that character, while quotes of other types have no special meaning. Thus, in C, opening a segment named Fred's Garage under a segment named buildings could be done as:

    Open_Segment ("buildings/'Fred''s Garage"); /* single quotes */
    Open_Segment ("buildings/\"Fred's Garage\""); /* double quotes */
    Open_Segment ("buildings/`Fred's Garage`"); /* back quotes */
The choice is left to the user as different programming languages and data affect which works better. Hoops will normally return special segment names using back quotes.

RESTRICTIONS

Although it is possible to do an Open_Segment() after an open geometry (e.g, Open_Face() ), without doing a close geometry (e.g., Close_Face() ), the Open_Segment() must not specify a relative pathname.

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 ()

See also
Close_Segment, Create_Segment, Flush_Contents, Rename_Segment, Delete_Segment, Set_Streaming_Mode, Insert_Polygon, Insert_Polyline, Insert_Marker.

◆ Open_Segment_By_Key()

void Open_Segment_By_Key ( HC_KEY  key)

Similar to Open_Segment(), but operates on an object referenced by an HC_KEY.

Parameters
key- Unique simple identifier for this segment. Returned to caller in Open_Segment() , accepted as an argument in Open_Segment_By_Key() .

DETAILS

No additional details. See Open_Segment()

◆ Open_Segment_Key_By_Key()

HC_KEY Open_Segment_Key_By_Key ( HC_KEY  parent_segment,
char const *  child_segment_name 
)

Similar to Open_Segment(), but opens a child segment under parent_segment instead of the currently opened segment.

Parameters
parent_segment- Unique simple identifier for the segment whose child segment will be operated on.
child_segment_name- The name of the segment to be opened.
Returns
A key to the opened child segment.

DETAILS

No additional details. See Open_Segment().