Brief Index      Full Index      I.M. Reference

Open_Segment


Functions

void Open_Segment (const char *segment)
HC_KEY KOpen_Segment (const char *segment)
void Open_Segment_By_Key (HC_KEY key)

Function Documentation

void 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.

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 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.

RESTRICTIONS

Although it is possible to do an Open_Segment() afer 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.

HC_KEY KOpen_Segment ( const char *  segment  ) 

Similar to Open_Segment(), but returns an HC_KEY to the object.

Parameters:
segment - Name of the segment.
Returns:
key

DETAILS

No additional details. See Open_Segment()

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 KOpen_Segment() , accepted as an argument in Open_Segment_By_Key() .

DETAILS

No additional details. See Open_Segment()

Main Index
Brief Index      Full Index      I.M. Functions