Functions | |
void | Bring_To_Front (const char *segment) |
void | Bring_To_Front_By_Key (HC_KEY key) |
void Bring_To_Front | ( | const char * | segment | ) |
This function has been deprecated. It is superseded by setting the hsra rendering option to priority.
segment | - Name of the segment(s) to be shuffled forward. |
If the subject of a call to Bring_To_Front() , specified either by key or by name, is a segment that has a Window attribute, then you're effectively asking to rearrange windows. A windowed segment that lies within a windowed segment is always drawn "on top" of the containing window. But when windowed segments lie side-by-side in the segment tree---when neither window is the owner of the other---the situation becomes ambiguous. If such windows don't overlap no problem arises. If they do overlap, Bring_To_Front() allows for making a choice. Set_Window() automatically calls Bring_To_Front() for each newly-created window, so the default is "newest in front." You might make an explicit call when, for example, the user's interest has shifted from one window to another. This is often indicated by some action such as touching a rear window. In summary, Bring_To_Front() can be used to specify the precedence of overlapping sibling windows.
If, on the other hand, the subject of a call to Bring_To_Front() is something other than a windowed segment---if it's geometry or a non-windowed segment---then you're forcing a particular drawing order onto the system. You would do this if you want to manually describe what's to have the appearance of being in front. Forcing a drawing order is sometimes more efficient than using the system's hidden-surface algorithm. It might be suitable for a paint program in which the user selects precedence, or useful for putting "annotations" on a scene that is otherwise all hidden-surfaced. You should not use Bring_To_Front() if you don't really care about the ordering. The system works more efficiently if it is permitted to order objects as it pleases.
Using Bring_To_Front() on 3-D geometry and nonwindowed segments only works within those segments where the "hidden surfaces" heuristic is not in effect. Hidden surfaces take priority over bring-to-front. So, to mix hidden-surface items and bring-to-front items in the same scene, do something like the following:
Open_Segment ("window") Set_Heuristics ("no hidden surfaces") Open_Segment ("A") Set_Heuristics ("hidden surfaces") /* regular hidden-surface picture, as needed */ Close_Segment () Open_Segment ("B") Set_Heuristics ("hidden surfaces") /* regular hidden-surface picture, as needed */ Close_Segment () /* now make "A" completely in front of "B"... */ Bring_To_Front ("A") Close_Segment ()
Note that "A" or "B" could have elected to continue with "no hidden surfaces". It might also make sense, depending on what "A" and "B" are, to turn off lighting visibility in one or the other. In addition, Bring_To_Front() can only be applied to siblings "A" versus "B." Bring_To_Front() does not apply to parent-child relationships.
This function can help resolve situations that arise with z-buffering where two surfaces have identical depth values but it is known which is supposed to be on top. For example, highlighting can be done this way, by drawing an extra copy with different attributes. This, combined with Control_Update() can be a powerful technique to highlight and de-highlight subsets of shells without ever incurring full updates.
Once something has been brought-to-front there is no simple way to put it back where it was. More objects can be put in front of the first, though, and the system will remember the entire ordering.
If the wildcard construction is used on Bring_To_Front() (segment) and there are conflicts, the system's choice of who really gets to be the one in front will not be predictable.
Entities within a streaming-mode segment can not be "brought-to-front".
Bring_To_Front() only works on the local level of the segment tree. If window A contains window B which contains window C, a bring-to-front of C will make C the foremost of all the windows within B. It won't make B foremost of the windows within A. If you want that to be true say so, separately.
void Bring_To_Front_By_Key | ( | HC_KEY | key | ) |
Similar to Bring_To_Front(), but operates on an object referenced by an HC_KEY.
key | - Open_Segment() , or any Insert routine. |