void Set_Color_By_Index (const char *types, int index)
 Changes the color to be used when rendering the contents of a segment. The color is defined indirectly, as a reference to the Color Map attribute. More...

Detailed Description

Function Documentation

◆ Set_Color_By_Index()

void Set_Color_By_Index ( const char *  types,
int  index 

Changes the color to be used when rendering the contents of a segment. The color is defined indirectly, as a reference to the Color Map attribute.

types- A list of which types of geometry are to be affected by this color specification.
index- The offset in the applicable Color Map at which the desired color will be found. The very first entry is at offset zero.


The usual way to specify colors in HOOPS is either via string descriptions (see Set_Color() ) or numerical descriptions (see Set_Color_By_Value() ). The concept of a color map was introduced to simplify Images where the same colors can be used over and over hundreds or thousands of times, and the full color specifications get tedious. The "current colormap" is an attribute just like all the rest of the HOOPS attributes—it can be pushed and popped as you go up and down the segment tree—and all it is a predefined list of colors. Images need to specify an offset to the colormap rather than the actual colors.
The "set color by index" routine extends this concept to all the various color attributes. If a line color, for example, is set by index then at Update time the system will look up the specified index in the current color map, fetch the color specified there, and proceed to draw lines. It's an extra level of indirection. If the index or the colormap is changed a different color will be fetched during subsequent Updates.
A legitimate use of coloring "by index" might be when you have computed a standard set of colors for use in a lighting or shading model, and those colors are going to be used many times over.
In addition, this can be used to set textures on individual faces of a shell or mesh, by createing a color map that is a list of textures.

The types used can include the following:

edges              The straight lines connecting the vertices of a polygon, shell,      
                   or mesh, or the border of an ellipse or circle.                      
faces              The interior filled areas of polygons, shells, meshes, ellipses,     
                   and circles.                                                         
back               Possible only when a polygon handedness is given and backplane culls 
                   are turned off, applies to the backplane of any face.                
markers            Applies to marker symbols.                                           
polylines          Applies to lines, polylines, and inked lines.                        
lines              Synonymous with "polylines".                                         
text               Applies to text strings.                                             
geometry           Shorthand for faces and edges (i.e., surfaces), markers,             
                   polylines, and text all at once.                                     
windows            Used for window backgrounds.                                         
window contrast    Used when window backgrounds require a contrasting color,            
                   either for drawing window frames or for drawing window pat           
face contrast      Used when a contrasting color is required for drawing pat            
                   terned faces.                                                        
lights             Used for any light sources within its scope. Does not affect         
                   the color of a light located elsewhere in the segment tree but       
                   shining into this part of the tree. The "lightness" of the color     
                   controls the brightness of the light.                                
lighting           A synonym for "lights".                                              
ambient            If there are no light sources in a given scene, the "ambient"        
                   light color is ignored. If there is at least one light, HOOPS        
                   will do a full lighting calculation and the "ambient" color will     
                   define a diffuse background lighting coming from all direc           
                   tions. You would usually use a combination of specific light         
                   sources plus ambient light. Ambient light applies to all geom        
                   etry within its scope in the segment tree. It is usually specified   
                   at the window level.                                                 
ambient light      A synonym for "ambient".                                             
polygon contrast   A synonym for "face contrast". "Face contrast" is preferred.         
polygons           Shorthand for both faces and edges.                                  

Lowercase versus uppercase is not significant. Leading and trailing blanks do not matter. The trailing "s" on "edges", "faces", "windows", etc., can be omitted. More than one color type can be specified at a time. You should separate the names with commas within the quoted string.
Many different entities can refer to the same color map entries. Thus, modifying a color map might change many parts of your picture. It's suggested that color maps not be used to change, say, all the polygon colors. Indiscriminate use of color maps and indices can cause your program to become disorganized. Instead you should either 1) put the polygon color specification high enough in your segment tree for the single setting to affect everything, or 2) use a wildcard segment specification on a call to QSet_Color() that "catches" all the necessary segments.
Note that even though there are three ways of defining color attributes—regular, "by value", and "by index"—they all operate on the same attribute(s). An edge color, for example, set by index overrides any previous edge color, no matter how the old one was set. The same holds true for "regular" and "by value".


The color map that the index matches up with should be set at the same level or higher in the segment tree—the lookup is done at the instant the index is encountered.

Use UnSet_Color() or UnSet_One_Color() (see Set_Color() ) to remove a color-by-index.
If you are setting local vertex or face colors in a shell or mesh, Set_Color_By_FIndex() may be more appropriate to use than Set_Color_By_Index() .


See also
Set_Color_Map, Modify_Color_Map, Insert_Image, Set_Color, Set_Color_By_Value, Set_Color_By_FIndex.