HC_Set_Visibility

void HC_Set_Visibility(char const *list)

Allows another level of control in determining whether a segment is visible. Useful for flicking graphics on and off without disturbing their place in the segment tree.

You may find it convenient to create segments before it’s actually time to let them appear on the screen, or to keep something around even though it’s not needed at the moment. There are three basic ways of doing this. One way is to make graphics appear and disappear is to use Rename_Segment() to move segments from inside the “?Picture” tree, where they’re visible, to somewhere else, such as “?Home/boonies”, where they won’t be. A gentler approach is to build the occasionally-used segments in the “?Include Library” segment, then to Include them or Flush the include’s as needed. And lastly, the gentlest approach is to call Set_Visibility() with a parameter of “Off”. Turning Visibility off doesn’t disrupt your segment structure at all; think of it as setting the color of everything in the segment to “clear”. The segment’s still there - it’s just invisible.

Supported Options:: cut edges, cut geometry, edges, adjacent edges, generic edges, hard edges, interior silhouette edges, mesh quads edges, non-culled edges, perimeter edges, faces, geometry, images, lighting, lines, vertices, markers, polygons, polylines, shadows windows
DETAILS

You can specify “on” or “off” for Visibility, or you can go into detail. The following choices are recognized:

cutting plane=on/off

“Cutting plane=off” will turn off any cutting planes within its scope, however, lights are exempted from the cutting action. If “cutting planes” visibility is “off” for a branch of the tree, a cutting plane set elsewhere in the segment tree will not affect the geometry in this part of the tree.

cut edges = (on/off) [on]

Toggles visibility of cutting lines in shells and meshes. The visibility of cutting planes needs to be “on” in order for cutting lines to be visible. Default visibility is “on”.

cut geometry = on/offcut geometry = (faces=on/off, edges=on/off)

Sets visibility of cutting geometry. See also the cut geometry options in Set_Rendering_Options and Set_Color. Default is “cut

geometry = on”.

edges=on/off/<special edge options>

The edges of filled figures (polygons, circles, ellipses, shells, and meshes) will be [will not be] drawn. “Special edge

options” are available for shells and meshes.

The default is “edges=on”. As with the regular visibilities the phrase “=on” can be omitted, and a “no” in front (“no

perimeters”) can replace an “=off”. If more than one suboption is named they should be separated by commas and surrounded by parentheses, and the last in the list takes precedence. For example, “edges=(off, perimeters, interior silhouettes)” turns two suboptions on and the other two off.

Note that local edge visibility settings (achieved with Open_Edge() - Set_Visibility() - Close_Edge() ) will always take precedence over the segment edge visibility setting. Also, “on,” “off” and the special options are the only choices permitted within an individual open edge (in the present implementation.) The default is “edges=on”.

<Special Edge Options>

Within the “edge” visibility item you can specify “on” or “off” or you can go into detail - there are a number of suboptions available. Each edge visibility suboption is set and unset separately; each suboption inherits down the segment tree separately. The following choices are recognized:

edges=(adjacent=on/off) An adjacent edge is defined as an edge that is attached to at least one visible face. If “on”, then at least those edges that have the “adjacent” property will be visible.

edges=(adjacent only) Same as “edges=(everything=off, adjacent=on)”.

edges=off (or everything=off or nothing
)

Same as “edges=(adjacent=off, interior silhouettes=off, perimeters =off, mesh quads=off, generics=off)”. (Note that “generics=off” will
not necessarily give the same visual effect as “off”).

edges=on (or everything=on
)

Same as “edges=(adjacent=on, interior silhouettes=on, perimeters=on, mesh quads=on, generics=on, nonculled=on)”. (As it happens, just saying “generics=on” will give the identical visual effect.)

edges=(generics=on/off) If “on”, every edge will be drawn, including all the interior edges that have none of the other above properties. If “off”, the preceding suboptions take control.

edges=(hard=on/off)
If “on”, edges will be drawn between faces that come together at a crease angle less than that defined by the “geometry options

= (hard edge angle = x)” Rendering_Option.

edges=(interior silhouettes=on/off) If “on”, then at least those edges that have the “interior silhouette” property will be visible. The “interior silhouette” property is defined for each edge as having two attached non-invisible faces, one of which is facing forward and one back on the screen. “Noninvisible” means the face has not been eliminated by doing an Open_Face() - Set_Visibility() - Close_Face() sequence. If more than two faces are attached to an edge the behavior is undefined. Only shells and meshes can have interior silhouette edges.

edges=interior silhouettes only Same as “edges=(everything=off, interior silhouettes=on)”. Note that this forces silhouette edges “on” (of course.) If you wanted to limit the local edge possibilities to silhouette edges, but still allow simple on or off edge visibility to inherit from above, you could do it by saying “edges=(perimeters=off, mesh quads=off, generics=off)”, omitting any local definition for silhouette visibility.

edges=(mesh quads=on/off) If “on”, then at least those edges that have the “mesh quad” property will be visible. A mesh quad edge is every edge in a mesh except the diagonal ones. Only meshes have mesh quad edges. The same visual effect could be achieved by opening and turning off each diagonal edge individually (via Open_Edge() and Set_Visibility() ); the “mesh quads” option is offered here as a convenience.

edges=mesh quads only Same as “edges=(everything=off, mesh quads=on)”. Again, “edges=(interior silhouettes=off, perimeters=off, generics=off)” might be a useful alternative.

edges=(nonculled=on/off) Same as an “adjacent” edge except that one of the faces it is attached to is not being backplane culled.

edges=(nonculled only) Same as “everything=off, nonculled=on”.

edges=(perimeters=on/off) If “on”, then at least those edges that have the “perimeter” property will be visible. An edge is considered to be on the perimeter when it has one, but not two, attached non-invisible faces. Note that by this definition a perimeter edge is a sort of “exterior” silhouette; it is not uncommon to display the perimeter edges in combination with the interior silhouette edges. “Non-invisible” is defined as in interior silhouettes. If more than two faces are attached to an edge the behavior is undefined. Only shells, meshes, and grids can have edges which are not on the perimeter.

edges=perimeters only
Same as “edges=(perimeters =on, adjacent=off, interior silhouettes=off, mesh quads=off, generics=off)”. Again, note that “edges

= (adjacent=off, interior silhouettes=off, mesh quads=off, generics= off)” might be as useful.

faces=on/off

The interior parts of filled figures (polygons, circles, ellipses, shells, and meshes) will be [will not be] drawn. When edges are on and faces are off you get a skeleton of the object.

Note that local face visibility settings (achieved with Open_Face() - Set_Visibility() - Close_Face() ) will always take precedence over the segment face visibility setting. Also, “on” and “off” are the only choices permitted within an individual open face (in the present implementation.) The default is “faces=on”.

geometry=on/off

Specifying “geometry” is the same as specifying edges, faces, lines, markers, images, polygons, cutting planes, lights and text all at once.

images=on/off

Images will be [will not be] visible.

lighting=on/off/(edges = on/off)/(faces = on/off)

“Lighting=off” will turn off any light sources within its scope. It also has the property of preventing light sources elsewhere in the segment tree from shining on the geometry in this part of the tree. In addition to specifying lighting visibility for the entire scene, you can individually determine if lighting affects the faces and/or edges of HOOPS shell and mesh primitives.

lights=on/off/(edges = on/off)/(faces = on/off)

“Lights” and “lighting” are the same.

lines=on/off

Lines and polylines will be [will not be] visible.

vertices=on/off

Shell vertex markers will be [will not be] visible.

markers=on/off

Markers will be [will not be] visible.

Calling HC_Set_Visibility (“markers = on”) is all-inclusive in that it will affect both the visibility of ‘vertex’ markers at shell/mesh vertices, as well as ‘regular’ markers (those denoted by Insert_Marker() ). Calling Set_Visibility(“markers only =

[on/off]”) controls just the ‘regular’ markers and has no affect on the ‘vertex’ markers.

Note that local marker visibility settings (achieved with Open_Vertex() - Set_Visibility() - Close_Vertex() ) will always take precedence over the segment marker visibility setting. Also please note that “on” and “off” are the only choices permitted within an individual open vertex (in the present implementation.) The default is “markers=on”.

off (or everything=off) Unless a lower-level segment specifies differently, nothing - neither geometry nor windows - will be eligible to be drawn on the screen.

on (or everything=on) Windows and all kinds of geometry will be visible.

polygons=on/off

Both edges and faces will be [will not be] drawn in.

polylines=on/off

Lines and polylines will be [will not be] visible. “Lines” is a synonym for “polylines” here.

shadows = [()]

The “shadows” visibility option allows the user to control the effect that certain lights and geometry have on shadows. Legal choices for option are as follows:

on A synonym for “shadows = (casting = on, receiving = on, emitting = on)”.

casting [= on/off] Ensures that the geometry contained in a segment and sub creates a shadow. Note that only faces can cast shadows. Images, text, lines and edges do not.

receiving [= on/off] Ensures that the geometry can have a shadow applied to it. Any geometry that can be lighted can receive a shadow.

emitting [= on/off] Ensures that the lights contained within are the lights which are used to cast the shadows. Only distant lights can cast shadows. This parameter should be set at the segment where the light resides.

The casting, emitting, and receiving options can be set independent of each other. The default setting is “shadows=off”. A more detailed discussion on shadow maps can be found in the programming guide.

NOTE: this setting is effective only when the shadow map = on Rendering_Option is set. There are also restrictions of what objects can or cannot cast shadows under certain conditions.

string cursors=on/off

String cursors will be [will not be] visible.

text=on/off

Text strings will be [will not be] visible.

windows=on/off

Windows declared at this level or deeper will be [will not be] visible. Default value is “on”.

If you want to list more than one choice, separate them by commas inside your quoted string: “windows=on, faces=off,

markers=off”. The “s” on the end of “markers”, “faces”, etc., is optional. Blanks around equals signs and around commas are also optional. Uppercase versus lowercase does not matter.

Using the “everything” choice is equivalent to setting all of the “particular flavor” choices simultaneously. In terms of the segment tree, there is nothing special about setting everything: each individual setting - edge visibility, text visibility, etc. - always inherits independently up and down the tree.

You can mix a general choice with particular choices: “everything=on, images =off”, for example, will result in everything being visible except images. The rule is that whatever specification comes last in the list wins.

Windows are special. If a given window comes out “invisible”, then nothing within that window can possibly be seen. If you are looking for a way to turn on or off the border that is drawn around a window, see Set_Window_Frame().

NOTES

Like all HOOPS on or off attributes, Visibility is three-valued: it can be set explicitly “on” for a segment, it can be set explicitly “off” for a segment, or not set at all and inherited from the owning segment. To allow the full benefit of the inheriting of Visibility - which is really the inheriting of in visibility - your programs will probably work better if you use an “UnSet Visibility” rather than a “Set (on)” to cancel a “Set (off)”. Visibility “on” should rarely be used.

When you call UnSet_Visibility() , all the visibilities in the segment are thrown away. Use UnSet_One_Visibility() to discard the setting for one without disturbing the rest.