HC_Set_Color

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.

Supported Options:: ambient, ambient light, ambient up, ambient down, back, cut edges, cut faces, cut geometry, edges, edge contrast, emission, faces, face contrast, geometry, lights, lighting, lines, line contrast, markers, marker contrast, polygon contrast, polygons, polylines, text, text contrast, vertex contrast, vertices, windows, window contrast
DETAILS

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

diffuse

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

specular reflectance

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.

gloss

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:

emission: The emission color channel is so named because an object with an emissive color can be thought of as “emitting” that color. Although the geometry does not become a light source, the emission value is added to the diffuse and ambient values during lighting calculations. This means the emission color contributes to the color of the object regardless of how other lights affect the geometry. If there are no lights in the scene, the emission value is ignored.

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:

environment = <texture_name>: A texture defined properly to be used as an environment including cube maps.
mirror = <color_name>: A color to be used as the mirror color. Similar to a transmission setting on faces, the average intensity of the three channels determines the relative contribution of the environment vs the underlying color (or diffuse texture).

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)")

bump = <texture_name>

DIFFUSE TEXTURE CHANNEL

In effect, HOOPS supports multiple diffuse channels: one standard - “diffuse color” - and one specifically for textures

”diffuse texture” - which is a sub-channel of, and therefore inherits from, the standard diffuse color channel.

When a modulating texture (see the “modulate” option in Define_Texture()) is applied on an object’s diffuse texture channel, the color of that texture can be changed without affecting other objects. In turn, the standard diffuse channel can be changed without stomping on the texture. For example, this could allow a cabinet assembly with an oak texture to be selected and highlighted without losing the appearance of the wood grain.

To do this, users must set the color on the diffuse texture channel using the “diffuse color” sub-option. They must also make sure that the textures are defined with the “modulate” option. The effect amounts to a tinting of the texture rather than a replacement of it.

Multiple diffuse textures can be overlaid onto one another. This capability is really only useful, however, if the textures applied to the channels after 0 have at least some transparency on them (as they would otherwise completely replace the channels before them). Textures after channel 0 will automatically be treated as if they had the “decal” option set on them (see Define_Texture).

If color channel is set as simply “diffuse” (or if it is left unspecified as the default), the color is a complete replacement for both diffuse color and diffuse texture. If, however, the channel is specified as “diffuse color”, the diffuse texture (if there is one) will inherit from above. Conversely, setting it as “diffuse texture” will still allow diffuse color (which will always be present) to inherit.

Individual diffuse texture channels can also inherit and mix. To this end, there are two specially reserved texture names that have special meaning. “*” means that the texture on that channel should be inherited from above (or left alone if already set locally). “-” means that it should not be inherited from above, but no texture should be put in its place. If the last texture in the list is “*”, it is implicitly extended to all subsequent channels. So, for example,

Set_Color("diffuse texture = (-, mystripes, *)")

unsets channel 0, sets channel 1 to a texture named “mystripes”, and leaves all subsequent channels be.

Set_Color("diffuse texture = -")

unsets all diffuse texture channels.

Attenuation colors can also be applied to textures by adding a color name (or rgb value formatted as “r=xxx, g=xxx, b=xxx”) in front of the texture. So, for example,

Set_Color("diffuse color = red, diffuse texture = (green mystripes)")

Would attenuate (the same thing as modulate, i.e. multiply) the mystripes texture with green. If the mystripes definition had the “modulate” setting on its definition, the result would modulate the underlying diffuse color. If the mystripes definition had the “decal” setting, it would be overlaid on top (and red would shine through any transparent parts of the texture). If the mystripes definition had neither “modulate” nor “decal”, the diffuse color would be ignored. Transparent textures with decal can be drawn much faster than transparent textures without decal, since it means that the objects will not have to be drawn in a view-dependent order (unless the surface it is being drawn onto is itself transparent because of a “transmission = xxx” color setting somewhere).

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))")

NOTES: In special cases, you might want to set your colors numerically (see Set_Color_By_Value() for details) or indirectly (see Set_Color_By_Index() ). Setting color “by value” might be appropriate if your program is computing the color parameters. Setting colors “by index” allows indirect control of color usage and is compatible with HOOPS “Image” conventions. Special face colors that take a color as an argument (i.e. everything except gloss) can also be set by value with explicit floating point values

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.