HC_Set_Color
-
void
HC_Set_Color(char const *color_spec) - void HC_Set_Color(char const color_spec)
Changes the color to be used when rendering the contents of a segment. Can also be used to select surface properties for use in lighting mode, and for special texture mapping effects.
Set_Color() is the general-purpose “draw with this color please”. You can just name a color, or you can go into detail and also name the particular kind of geometry the color applies to. When in the HOOPS lighting mode, Set_Color() also allows you to describe the reflection and transmission characteristics (material properties) of illuminated surfaces. Additionally, you can specify the name of an image or texture that should be used just like a color.
The color portion of color_spec is in the form of a description, such as “pinkish sunset-orange” or “pale gray” or “R=0.8 G=0 B=0.1”. Entirely new color names can be created with Define_Color_Name() . Click here for a listing of the color set supported by HOOPS. Uppercase versus lowercase does not matter.
If you just name a color in color_spec, all the different kinds of geometry are given that color (window and contrast colors are unaffected).
If you want to be more specific, color_spec can also be a character string that consists of the type of geometry to be colored, an equals sign, and the color to be used. For example: “lines=red”. Blanks can be inserted around the words. More than one specification can be made in a given color_spec by embedding a comma as in the following example:
Set_Color("lines = red, edges = green")
and identical colors can be folded together:
Set_Color("lines=edges=green, faces=markers=blue")
Colors can be set on the following:
- ambient light 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 directions. You would usually use a combination of specific light sources plus a small amount of ambient light. Ambient light applies to all geometry within its scope in the segment tree. It is usually (but not necessarily) specified at the window level. NOTE: Ambient color can be set on a per-light basis by opening the light (see Open_Geometry) and changing the “ambient” color attribute.
- ambient A synonym for “ambient light”.
- ambient up = rgb and ambient down = rgb Setting both “ambient up” and “ambient down” is a synonym for the “ambient” setting. Both the up and down colors must resolve to simple rgb values (i.e. no transparency and no textures). See also the “ambient up vector” setting in Set_Rendering_Options(). 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 directions. One would generally use a combination of specific light sources, plus a small amount of ambient light. Ambient light applies to all geometry within its scope in the segment tree. It is usually (but not necessarily) specified at the window level. NOTE: Ambient color can be set on a per-light basis by opening the light (see Open_Geometry()) and changing the “ambient” color attribute. The default is “ambient = dark gray”.
- back Possible only when a polygon handedness is given and backplane culls are turned off, applies to the backplane of any face.
- cut edges Lines of intersection between a cutting plane and a surface.
- cut faces Surface of intersection formed by a cutting plane and cut edges
- cut geometry Synonym for ‘cut edges’ and ‘cut faces’
- edges The straight lines connecting the vertices of a polygon, shell, or mesh, or the border of an ellipse or circle.
- edge contrast Used when a contrasting color is required for drawing edges.
- emission Used to set the emission value for faces. Unlike ambient light, emissive light is additive rather than multiplicative. This means the emission color contributes to the color of the object regardless of diffuse light. If there are no lights in the scene, the emission value is ignored.
- faces The interior filled areas of polygons, shells, meshes, ellipses, and circles (surfaces). Unlike other types of geometry, faces have additional properties besides a primary color.
- face contrast Used when a contrasting color is required for drawing patterned faces.
- geometry Shorthand for faces, edges, markers, polylines, and text all at once.
- 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”.
- lines Synonymous with “polylines”.
- line contrast Used when a contrasting color is required for drawing lines.
- markers Applies to marker symbols.
- marker contrast Used when a contrasting color is required for drawing markers.
- polygon contrast A synonym for “face contrast”. “Face contrast” is preferred.
- polygons Shorthand for both faces and edges.
- polylines Applies to lines, polylines, and inked lines.
- text Applies to text strings.
- text contrast Used when a contrasting color is required for drawing text.
- vertex contrast Used when a contrasting color is required for drawing vertices.
- vertices Applies to shell vertex markers.
- windows Used for window backgrounds. If the name is a texture that was created with six source images, then a skybox will be created within the scene.
- window contrast Used when window backgrounds require a contrasting color, either for drawing window frames or for drawing window patterns.
The trailing “s” on “edges”, “faces”, “windows”, etc., can be omitted. If specifications overlap (“geometry=white, lines=black”), the last specification wins.
If an absolute color-space location is used for the color name, the string should look like “X=val Y=val Z=val”, where the val’s are floating-point numbers and the “XYZ” is any one of the following:
--------------------------------------------------------------- "HLS" For hue, lightness, and saturation (a "double cone", with black and white at the tips). "HSV" For hue, saturation and value, (a "single cone" standing on its point, with black at the tip and white at the center of the base). "HIC" For hue, intensity and chromaticity (a cylinder, with black and white at the two ends). "RGB" For red, green, and blue (a cube, with white, black andi six primary colors at the corners). ---------------------------------------------------------------All numeric values must be in the range of zero to one inclusive, except for hues, which range from zero to 360 degrees. If a hue is outside this range, the system will normalize the value.
Here is an example of explicit values in the string for the RGB color space:
Set_Color("lines = edges = (r=0.5 g=1 b=0)")
SPECIAL FACE COLORING OPTIONS
Normally only a single color is needed to describe geometry (for example, “lines=red”) Faces, however, can have more complicated definitions. These more complicated settings can be used to enable the following:
- Reflectance and Interaction with Lighting: ambient, diffuse, specular and gloss options
- Texture Mapping and Environment Mapping: environment and bump options.
- Diffuse Texture Channel and Texture Color Modulation
- Two-Sided Coloring
- Transparency (a.k.a transmission)
REFLECTANCE AND INTERACTION WITH LIGHTING
If lights are present in a scene, HOOPS computes the appearance of faces based on the interaction of light with the surface material as viewed by the camera. The computed appearance of a surface in lighting mode is the sum of independent components or channels: an ambient reflection, a diffuse reflection, and a specular reflection.
This is the primary color of an object: a red apple has a red diffuse color. Diffuse light reflection is the opposite of a “shiny” (specular) reflection since the light reflected has no directional component (omni-directional scattering).
Note that:
Set_Color ("faces = (diffuse=black)")
is equivalent to:
Set_Color ("faces = black")
because “diffuse” is the default color channel.
“Specular” light reflection is the opposite of diffuse reflection - highly specular surfaces are hard and shiny, causing the specular reflected light to have a strong directional component (little scattering). The angle at which light strikes a specular surface is equal to the angle of the reflected ray (a view dependant reflection).
The specular reflectance term considers only light that reflects directly from a point light source (distant, local, and spot lights) off a specular surface to the camera. This reflection approximation does not include any light that would require more than one bounce to reach the camera, nor does it include an actual reflected image of neighboring surfaces as a real-world mirror reflection would.
With most nonmetallic objects, the specular reflection color is a shade of white - meaning that the specular reflected light maintains the same color (hue) as the light source. For example, the “glare” off a shiny red apple is the color of the light source (white), not the color of the apple (red).
Set_Color ("Faces = (specular=black)")
results in a dull, non-specular surface; while
Set_Color ("faces=(specular=white)")
gives a shiny material.
Some metals, however, have “colored” specular reflections. For example, the “glare” from a piece of polished brass (illuminated by a white light) has a yellow-orange tint. This specular tint could be described by
Set_Color ("faces = (specular = orangish white)")
Some devices (e.g. lighting interpolation = phong on OpenGL as of 8.0) may decide to restrict specular materials to grey scales, in which case one solution to capture “metallic” surfaces would be to alter the color of the lights.
Gloss is another setting that helps to determine the specular response of a material. It is a single floating point value that describes the “focus” of specular reflections off a surface. A problem with point light sources (distant, local, and spot lights) is that they are infinitely small. The viewed specular “glare” of a point source off a perfect mirror would be correspondingly small (a single pixel). The gloss value changes the area of the “glare” off a surface - a high gloss value gives a small, focused glare; a low gloss value results in a less polished, more scattered reflection. Gloss is an approximation that can be thought of as giving point light sources area, or as a way of partially scattering specular surface reflections. Gloss is always positive, and most surfaces have a gloss in the range from 1.0 to 30.0.
The default is “faces = (diffuse = black, specular = white, gloss = 5.0)”.
You might use the emission channel if you were modelling an illuminated light bulb. You wouldn’t want the surface of the bulb to be in shadow or otherwise affected by the overall brightness of the scene - you would want it to appear to be a light source itself. Giving the light bulb an emissive color adds that color to the calculated value for the bulb’s faces. Keep in mind that giving a value to the emission channel does not brighten the rest of the scene in any way. If you wanted to make the light bulb appear to light other geometry, you would also have to add a true light somewhere near the bulb geometry. To make a white emissive surface, you would use this code:
Set_Color ("faces = (emission = white)")
TEXTURE MAPPING
In place of the colors specified for diffuse and specular, a named image can be specified instead. The image is associated with the name at the time of insertion, as in the following call:
Insert_Image (x, y, z, "rgb, name = my_image_name", w, h, data) Set_Color ("faces = (specular=white, diffuse=my_image_name)")
Alternatively, the texture definition can also come from Define_Texture() , if control over more than just the image source is required (e.g. clamp mode, parameterization source, etc…), as in the following example:
Insert_Image (x, y, z, "rgb, name = my_image_name", w, h, data) Define_Texture ( "my_texture_name", "tiling, parameterization source = world, source = my_image_name" ) Set_Color ("faces = (specular=white, diffuse=my_texture_name)")
Named images and texture definitions are global resources (except in the case of Define_Local_Texture), so some attention is required towards avoiding name collisions. Texture maps can also be used with HOOPS’ windows, to specify an image that is to be used as a backdrop. To achieve this, an image is inserted with a name specified. That image name is then used in the setting of color for the HOOPS window as in:
Insert_Image() (x, y, z, "rgb, name = my_backdrop", w, h, data) Set_Color ("window = my_backdrop");
Texture settings have no effect if parameters (a.k.a. uv texture coordinates) are neither explicitly set (e.g. via Set_Vertex_Parameters()) or implicitly set (e.g. via parameterization source = xxx). No texture mapping is enabled by default.
ENVIRONMENT MAPPING
The following options of face-color invoke HOOPS’ environment mapping:
Example:
Set_Color ("faces=(diffuse=white, environment=metal, mirror=grey)")
No environment mapping is enabled by default.
BUMP MAPPING
Bump Mapping is a technique to add additional detail to a textured or non-textured surface by pertubating its surface normal during the lighting stage based on a texture lookup. A bump-map in HOOPS is treated very similar to a standard 2-dimensional RGB texture in which the RGB components represent a surface normal instead of a color value. These values are interpreted as quantized vectors in the range of [-128,127].
In some bump-mapping implementations height maps are used instead of normal maps. Those need to be converted to normal-maps first before they can be used in HOOPS.
Since bump mapping is an operation that affects only the surface normals of the material, it has no effect unless lights are present and their visibility is on.
Example:
Set_Color ("faces=(bump=stone_normal_map)")
DIFFUSE TEXTURE CHANNEL
In effect, HOOPS supports multiple diffuse channels: one standard - “diffuse color” - and one specifically for textures
Set_Color("diffuse texture = (-, mystripes, *)")
Set_Color("diffuse texture = -")
Set_Color("diffuse color = red, diffuse texture = (green mystripes)")
TWO-SIDED COLORING
HOOPS supports two-sided coloring of faces by simply setting different values for “front” and “back”, as in this example:
Set_Color("front = red, back = green")
For two sided coloring to be meaningful, however, there needs to be a definition of front and back. This definition is supplied with the “polygon handedness” option of Set_Heuristics. NOTE: Two-sided coloring cannot currently be applied to the individual faces in a shell.
TRANSPARENCY
Devices that support transparency generally require that transparent objects be deferred so that they can be sorted by depth. For that reason, making surfaces transparent will generally slow the rendering process. Several different options for transparency hidden surface removal algorithms are available in Set_Rendering_Options() (look for the “transparency” suboption). These various strategies control the trade-off between speed and quality of transparent geometry.
Set_Color("Faces=(transmission=black)")
describes a perfectly opaque surface,
Set_Color("faces=(transmission=white)")
describes a perfectly clear material, while
Set_Color("faces=(transmission=green)")
…describes a surface that is opaque to red and blue, but transparent to green. Transmission settings that are not grey-scale values (i.e. r=g=b) tend to map poorly to modern graphics hardware, and so may come at an even larger than normal performance penalty.
The accuracy of surface transparency is dependent on both hardware and the type of hidden surface removal being used. Some display devices have hardware to accelerate drawing of transparent surfaces, but allow only a degree of transparency rather than a color (in which case the intensity of color is used, but hue and saturation are ignored).
Not all devices or hidden surface algorithms are able to support transmission. Those that do not will render transparent geometry as opaque.
Set_Color("faces = (transmission = (r=0.2 g=0.2 b=0.2))")
If you are building three-dimensional figures from HOOPS polygons, shells, or meshes, and you’re not using lights, you will need to make sure that the “edges” are visible - otherwise you’ll just see a silhouette of the figure. To differentiate the edges, you will either need to draw patterned faces, or choose an “edge” color that is different from the “face” color.
Setting a particular color - line color, for example - on a segment causes that segment’s old line color setting to be discarded, but has no affect at all on any stored edge color, marker color, etc. However, the UnSet_Color routines discard all* the color information for the segment. For example, use UnSet_One_Color(“edges”) to discard just the “edge” color setting, or UnSet_One_Color(“faces=specular”) to discard the setting on the specular channel.
The default setting of the Color attribute - the setting on the root (“/”) segment - can be given a new initial value on most systems by means of the environment variable “HOOPS_COLORS”.
If a color is applied to* faces* without specifying a specific material property, the diffuse property is assumed. Thus,
Set_Color ("faces = red")
is identical to
Set_Color ("faces = (diffuse=red)")
Each of the face material components (diffuse, specular, gloss, etc.) inherits separately. It is therefore possible to change the specular color, for example, without modifying the other surface properties.
Since the illumination of a surface is the combination of several components (diffuse reflection, specular reflection, etc.), it is possible for a surface to be brighter than can be displayed - HOOPS “clamps” such colors to the legal maximum. To minimize the amount of color clamping, surfaces should not be highly reflective in several components at once.
When the string required to describe a material is lengthy, Define_Color_Name() may be useful. For example:
Define_Color_Name ("plastic", "plasticer", "plasticish", "diffuse = white, specular = white, gloss = 5.0, transmission = black")
would allow
Set_Color ("faces = plastic")
As with normal colors, material properties can be mixed. If in addition to “plastic”, we define
Define_Color_Name ("clear", "", "", "transmission = white")
and
Define_Color_Name("clay", "", "", "diffuse = brown, specular = gray,", "gloss = 3.0, transmission = black")
then several mixing versus replacing rules apply.
As with normal colors, color mixing is accomplished with the “-ish” or “-er” forms of a color. For example, “reddish blue” results in a near magenta color. Similarly, Set_Color() *(“faces = plasticish clay”)* results in a material similar to “clay”, but with each of the material properties modified to be closer to the settings of “plastic”.
In the case of Set_Color() *(“faces=clearish plastic”)*, “clear” does not have the same set of material properties as “plastic”. As such, “clearish” modifies only those channels that it has in common with “plastic” - in this case the transmission channel. The resulting color after mixing is a semitransparent plastic.
When two material descriptions are separated by a space (and no “-ish” or “-er” mixing is used) HOOPS replaces the material properties on the right of the space with those found on the left. For example, Set_Color() * (“faces=clear plastic”)* gives an entirely transparent plastic. This is identical to saying Set_Color() *(“faces=plastic, faces=clear”)*. Furthermore, Set_Color() *(“faces = clay plastic”)* simply defines a clay material.
When a simple color proceeds a material description, as in Set_Color() *(“faces = red plastic”)* or Set_Color() (“faces = reddish plastic”)*, the simple color is applied (replaced and mixed, respectively) to the diffuse channel.
If a set of material properties is declared without assigning it to “faces” (as in Set_Color() *(“plastic”))*, the description is assigned to all “geometry”. Since lines, markers, text, etc. don’t have surfaces, only the diffuse component is used.
In the current version of HOOPS, only diffuse colors may be set on shell or mesh vertices and faces. Other material components (such as specular color, gloss, etc.) must be set on a per-segment basis.
HC_Set_Color_By_Value, HC_Set_Color_By_Index, HC_Set_Color_By_FIndex, HC_Set_Color_Map, HC_Define_Color_Name, HC_Define_Texture, HC_Set_Rendering_Options, HC_Set_Line_Pattern, HC_Set_Edge_Pattern, HC_Set_Marker_Symbol, HC_Set_Face_Pattern, HC_Set_Text_Font, HC_Insert_Distant_Light, HC_Open_Face, HC_Open_Edge, HC_Open_Vertex.Parameters
color_spec: A specification for the desired color setting.