DAGeometry Class
The DAGeometry class is a class of three-dimensional objects that includes surfaces, lights, sounds, their attributes, and/or combinations of these elements. Like other Microsoft® DirectAnimation® objects, the value of the elements of the geometry can change over time.
In general, every geometry behavior is spatially infinite and of infinite resolution. Conceptually, each of the infinitely many points in the geometry has associated with it an opacity value, a color, a normal (used for lighting computations), a texture coordinate, a detectability value, and a single-channel sound emanating from that point (generally, this is silence).
Surface geometry is either detectable or not. If a surface is detectable, the geometry fires an event whenever the cursor passes over a surface point. Neither lights nor sounds are detectable (or pickable).
Light geometries include ambient lights, directional lights, point lights, and spotlights. Light geometries can be attributed with both color and distance attenuation.
A texture in a geometry is an image, the points of which are mapped to the surface of the three-dimensional object represented by the geometry. If there is no surface in the geometry, the texture is ignored.
A geometry can also be a sound. The sound is audible when the geometry is within the appropriate range of a microphone behavior.
The bounding box query is used to construct and compose media, and different types of images and behaviors provide specific bounding boxes. This means, for example, that the bounding box of an image is not defined as the smallest axis-aligned, enclosing region of the non-transparent parts of an image. Instead, bounding boxes are defined on a per-operation basis. The emptyGeometry object, for example, has its own definition of a bounding box, defined below.
Note that in order to use AmbientColor, Lighting, LightRangeAnim, LightRange, ModelClip, and Shadow functions, you must have Microsoft DirectX® 6.x or later installed. You will not get an error if you use these functions without DirectX 6.x. They will simply have no effect.
This class inherits from DABehavior.
For relevant functions and properties in the DAStatics class, see the following topics.
- DAStatics Functions Relevant to DAGeometry Objects
- DAStatics Properties Relevant to DAGeometry Objects
DAGeometry Functions
AmbientColor Specifies the ambient color of a DAGeometry object. Billboard Creates a new DAGeometry object that is oriented in the direction of the current camera, around a specified axis. BlendTextureDiffuse Specifies that the texture and the diffuse color of a DAGeometry object should blend, rather than override each other, which is the default. DiffuseColor Specifies the diffuse color of a DAGeometry object. EmissiveColor Specifies the emissive color of a DAGeometry object. LightAttenuation Creates a DAGeometry object in which any light sources have the specified attenuation. Same as LightAttenuationAnim except that the parameters are nonanimated numbers (doubles). LightAttenuationAnim Creates a DAGeometry object in which any light sources have the specified animated attenuation. LightColor Creates a DAGeometry object in which all embedded light sources have the specified color. Lighting Enables you to create a DAGeometry object that requires no lights. LightRange Creates a new DAGeometry in which any light sources have the specified maximum range. Same as LightRangeAnim except that the range is a nonanimated number (double). LightRangeAnim Creates a new DAGeometry in which any light sources have the specified maximum range. ModelClip Enables you to specify a plane in 3-D space and create a new geometry from only that part of the original geometry which is visible in front of the plane. Opacity Sets the opacity of all surfaces in the DAGeometry object to the specified value. Same as OpacityAnim except that opac is a nonanimated number (a double). OpacityAnim Sets the opacity of all surfaces in the DAGeometry object to the specified animated value. Pickable Makes a DAGeometry object pickable. PickableOccluded Makes a DAGeometry object pickable, including portions of the object that are blocked (occluded) by other geometries. Render Creates a DAImage object that is a two-dimensional projection of the DAGeometry object. RenderSound Creates a DASound object that represents the sound associated with the DAGeometry object. Shadow Creates a new DAGeometry object that is the shadow of the geometry this function is applied to. The shadow is generated by all the lights in the specified geometry being projected onto the specified shadow plane. SpecularColor Specifies the specular color of a DAGeometry object. SpecularExponent Specifies the specular exponent of a DAGeometry object. Same as SpecularExponentAnim except that the parameter is a nonanimated number (double). SpecularExponentAnim Specifies the animated specular exponent of a DAGeometry object, which determines its shininess. TextureImage Creates a new DAGeometry object by mapping the specified image to the surface of the original geometry object. Transform Creates a new DAGeometry object that is the result of applying the specified 3-D transformation to the original geometry object. Undetectable Creates a new undetectable DAGeometry object by mapping the specified image to the surface of the original object.
DAGeometry Properties
BoundingBox A read-only property that creates a bounding box (DABbox3) enclosing all the nontransparent portions of the DAGeometry.
DAGeometry Functions
This section contains reference material for the DAGeometry functions.
AmbientColor
DAGeometry Class
Specifies the ambient color of the new DAGeometry object. The ambient color is the color reflected in ambient light. You will almost always want to set this value to the same as the diffuse color. Thus, your material in shadow will be the color of the object, but darker. In some rare situations, you might want to set the ambient color of the object to be shifted to the hue of its neighboring surface colors. The bounding box is the bounding box of the underlying geometry.
Note You can only use this function with DirectAnimation version 6.x or later. You must also have DirectX 6.x or later installed for AmbientColor to work. You will not get an error if you use this function without DirectX 6.x. It will simply have no effect.
Syntax
geometryObj.AmbientColor( col )
Parameters
- col
- DAColor object that is the color.
Return Value
Returns the DAGeometry object.
Remarks
This attribute overrides previous values.
For more information, see Lights in the Programmer's Guide.
Billboard
DAGeometry Class
Creates a new DAGeometry object that is oriented in the direction of the current camera, around a specified axis.
Note You can only use this function with Microsoft DirectAnimation versions later than 6.0; for example, version 6.00.06.xxx or later. Versions with this function are available in Microsoft Internet Explorer 5, Microsoft Windows® 98 Second Edition, and Windows 2000.
Syntax
geometryObj.Billboard( axis )
Parameters
- axis
- DAVector3 object that specifies the axis of rotation. For more information, see Remarks.
Return Value
Returns the DAGeometry object.
Remarks
This function takes any geometry and aims it toward the current camera. You can use this to orient 3-D geometries relative to the camera.
The Billboard function affects only the object's orientation. This function doesn't change the position of the geometry. You can think of it as a smart swivel that turns the geometry toward the camera regardless of where you place it.
The axis parameter specifies the geometry's rotation axis, which also becomes the direction of the geometry's up vector. Put another way, the geometry is oriented so that its up direction points in the direction of axis, and then rotates about axis to show the camera as much of its front as possible. For example, for a tree billboard, axis would point up from the landscape, so that the tree would rotate about its trunk. The tree will always point up, regardless of the camera orientation.
You can pass in a zero vector as the axis parameter. In this case, the geometry is always aimed directly at the camera, and is rotated about the line of sight so that the geometry's up vector aligns with the camera's up vector. This is useful for annotation geometries. For example, if you have an annotation marker such as text on a panel on a 3-D object, you'd always want the text aligned according to the camera orientation. Then, as you rotate either the camera or the object, the text remains upright in the resulting view.
The Billboard function (and DirectAnimation in general) orients geometries from a standard position and orientation: the origin is considered the object center, and the object is considered to be aimed in the negative z-direction (in right-hand coordinates, away from the viewer), with the positive y-axis pointing up.
The LookAtFrom transform function takes a geometry in the standard position and orientation and then positions and orients it according to the supplied parameters. The Billboard function operates in much the same way, taking a geometry from the standard orientation and orienting it according to the Billboard parameter.
Example
Note You must have a version of DirectAnimation later than 6.0 installed to run this sample.
The following example code displays eight geese in space, rotating above a dark green ground plane. The camera is slowly rolling back and forth about 45 degrees to a side.
Initially, the duck geometries have a Billboard axis parameter in the positive y-direction. Because the camera is oscillating about the z-axis during the animation, this means that the up direction of the geometries will appear to rotate as well, maintaining their upright orientation with respect to the ground plane. This is useful for making billboards of geometries such as trees or telephone poles.
If the user clicks the left mouse button while the mouse pointer is over the sample window, the Billboard axis parameter changes to the zero vector. This causes the geometries to align their up direction with the camera up vector. Thus, the geometries will always appear upright with respect to the camera, regardless of camera orientation. This is useful for annotation objects, which maintain a consistent orientation in the view.
BlendTextureDiffuse
DAGeometry Class
Creates a new DAGeometry object and specifies whether in the new geometry the texture and the diffuse color of the geometry should blend. Without calling this function, they will not blend but will override each other.
Note You can only use this function with DirectAnimation version 6.x or later.
Syntax
geometryObj.BlendTextureDiffuse( blended )
Parameters
Return Value
Returns the DAGeometry object.
DiffuseColor
DAGeometry Class
Specifies the diffuse color of the new DAGeometry object. The diffuse color is the diffuse (or matte) reflective color of the surface. By default, the diffuse color is white. The bounding box is the bounding box of the underlying geometry.
Syntax
geometryObj.DiffuseColor( col )
Parameters
- col
- DAColor object that is the color.
Return Value
Returns the DAGeometry object.
Remarks
This attribute overrides previous values.
See Lights in the Programmer's Guide for more information.
EmissiveColor
DAGeometry Class
Specifies the emissive color of the new DAGeometry object. The emissive color is the color that the object emits independent of lighting. By default, the emissive color is white. The bounding box is the bounding box of the underlying geometry.
Syntax
geometryObj.EmissiveColor( col )
Parameters
- col
- DAColor object that is the color.
Return Value
Returns the DAGeometry object.
Remarks
This attribute overrides previous values.
See Lights in the Programmer's Guide for more information.
LightAttenuation
DAGeometry Class
Creates a DAGeometry object in which any light sources have the specified attenuation. Same as LightAttenuationAnim except that the parameters are nonanimated numbers (doubles).
If you have DirectX 5.x or later installed, this function will not do anything.
Syntax
geometryObj.LightAttenuation( const, linear, quadratic )
Parameters
- const, linear, and quadratic
- Values specifying the attenuation of a light source. These are nonanimated numbers (double values).
Return Value
Returns the DAGeometry object.
Remarks
An attenuation of (1, 1, 0) gives a linear attenuation that is useful for light falloff in a room. An attenuation of (1, 0, 1) gives a quadratic attenuation that simulates lights that are in the open, such as street lamps and headlights. This attribute overrides previous values.
LightAttenuationAnim
DAGeometry Class
Creates a DAGeometry in which any light sources have the given attenuation. The new attenuation is set to 1 / (const + linear * d + quadratic * d2) where d is the distance from the light to the object. By default, the attenuation coefficients are (1, 0, 0), which means no light attenuation. The bounding box is the bounding box of the underlying geometry.
If you have DirectX 5.x or later installed, this function will not do anything.
Syntax
geometryObj.LightAttenuationAnim( const, linear, quadratic )
Parameters
- const, linear, and quadratic
- DANumber objects specifying the attenuation of a light source. These must be animated numbers.
Return Value
Returns the DAGeometry object.
Remarks
An attenuation of (1, 1, 0) gives a linear attenuation that is useful for light falloff in a room. An attenuation of (1, 0, 1) gives a quadratic attenuation that simulates lights that are in the open, such as street lamps and headlights. This attribute overrides previous values.
LightColor
DAGeometry Class
Creates a new DAGeometry object in which all embedded lights have the specified color. By default, a light source is white. The bounding box is the bounding box of the underlying geometry.
Syntax
geometryObj.LightColor( col )
Parameters
- col
- DAColor object.
Return Value
Returns the DAGeometry object.
Remarks
This attribute overrides previous values.
Lighting
DAGeometry Class
Enables you to create a DAGeometry object that requires no lights. If the lighting parameter is False, the geometry displays its diffuse color or its texture, without shading, and you do not need lights. If the lighting parameter is True, the geometry needs lights.
Note You can only use this function with DirectAnimation version 6.x or later. You must also have DirectX 6.x or later installed for Lighting to work. You will not get an error if you use this function without DirectX 6.x or later. It will simply have no effect.
Syntax
geometryObj.Lighting( lighting )
Parameters
Return Value
Returns the DAGeometry object.
LightRange
DAGeometry Class
Creates a new DAGeometry in which any light sources have the specified maximum range. Same as LightRangeAnim except that the range is a nonanimated number (a double value).
Note You can only use this function with DirectAnimation version 6.x or later. You must also have DirectX 6.x or later installed for LightRange to work. You will not get an error if you use this function without DirectX 6.x. It will simply have no effect.
Syntax
geometryObj.LightRange( range )
Parameters
- range
- Nonanimated number (double) that is the maximum light range of a light source.
Return Value
Returns the DAGeometry object.
LightRangeAnim
DAGeometry Class
Creates a new DAGeometry in which any light sources have the specified maximum range. The light range is specified in world coordinates (the final coordinate system of the rendered geometry).
Note You can only use this function with DirectAnimation version 6.x or later. You must also have DirectX 6.x or later installed for LightRangeAnim to work. You will not get an error if you use this function without DirectX 6.x. It will simply have no effect.
Syntax
geometryObj.LightRangeAnim( range )
Parameters
- range
- DANumber object that is the maximum light range of a light source. These must be animated numbers.
Return Value
Returns the DAGeometry object.
ModelClip
DAGeometry Class
Enables you to specify a plane in 3-D space and create a new geometry object from only that part of the original geometry which is visible in front of the plane.
Note You can only use this function with DirectAnimation version 6.x or later. You must also have DirectX 6.x or later installed for ModelClip to work. You will not get an error if you use this function without DirectX 6.x or later. It will simply have no effect.
Syntax
geometryObj.ModelClip( planePt, planeVec )
Parameters
Return Value
Returns a DAGeometry object that is the part of the original geometry still visible after the plane slices 3-D space.
Opacity
DAGeometry Class
Sets the opacity of all surfaces in the DAGeometry object to the specified value. Same as OpacityAnim except that opac is a nonanimated number (a double).
Syntax
geometryObj.Opacity( opac )
Parameters
- opac
- A double value representing the opacity. The geometry is fully opaque if the value is 1, and fully transparent if the value is 0. This is a nonanimated number.
Return Value
Returns the DAGeometry object.
OpacityAnim
DAGeometry Class
Sets the opacity value for all surfaces to opac. Opacity values can range from 0.0 to 1.0. If the corresponding DANumber object has a value outside this range, the integer part of the value is discarded and only the fractional part is used. By default, the opacity is 1.
Syntax
geometryObj.OpacityAnim( opac )
Parameters
- opac
- DANumber object representing the opacity value. The geometry is fully opaque if the value is 1, and fully transparent if the value is 0. This must be an animated number.
Return Value
Returns the DAGeometry object.
Remarks
This function composes values. The resulting opacity is the new value times the old value.
Pickable
DAGeometry Class
Makes a DAGeometry object pickable. Use this function along with the returned DAPickableResult object to create a reactive behavior (when the mouse is in the pickable area, an event occurs).
The behavior of a "pickable" image is identical to that of an ordinary image until the mouse is in the pickable region and there are no geometries (other than undetectable ones) between it and the mouse. Then, an event (created in DAPickableResult) occurs.
Syntax
geometryObj.Pickable( )
Return Value
Returns the DAPickableResult object.
PickableOccluded
DAGeometry Class
Makes a DAGeometry object pickable, including portions of the geometry that are blocked (occluded) by other geometries. Use this function along with the returned DAPickableResult object to create a reactive behavior (when the mouse is in the pickable area, an event occurs).
The behavior of a pickable-occluded image is identical to that of an ordinary image until the mouse is in the pickable region. Then an event (created in DAPickableResult) occurs. This event occurs whether or not there are other geometries between it and the mouse.
Syntax
geometryObj.PickableOccluded( )
Return Value
Returns the DAPickableResult object.
Render
DAGeometry Class
Creates a DAImage object that is a two-dimensional projection of the geometry. The camera parameter defines how the geometry is projected into two dimensions. The resulting image is infinite in extent. The bounding box of a rendered geometry is the projection of its three-dimensional bounding box onto the image plane, aligned along the axis.
Syntax
geometryObj.Render( camera )
Parameters
- camera
- DACamera object.
Return Value
Returns the DAImage object.
RenderSound
DAGeometry Class
Creates a DASound object that represents the sound associated with geometryObj as detected by the given microphone.
Syntax
geometryObj.RenderSound( mic )
Parameters
- mic
- DAMicrophone object.
Return Value
Returns the DASound object.
Shadow
DAGeometry Class
Creates a new DAGeometry object that is the shadow of the geometry object it is applied to. The shadow is generated by all the lights in geoContainingLights, projected onto the shadow plane specified by planePoint and planeNormal.
Note You can only use this function with DirectAnimation version 6.x or later. You must also have DirectX 6.x or later installed for Shadow to work. You will not get an error if you use this function without DirectX 6.x or later. It will simply have no effect.
Syntax
geometryObj.Shadow( geoContainingLights, planePoint, planeNormal )
Parameters
Return Value
Returns the DAGeometry object.
Remarks
This function creates just the shadow of the geometry object it is applied to. If you want both the geometry object and its shadow, you need to create a union (with UnionGeometry) of the geometry and its shadow.
SpecularColor
DAGeometry Class
Specifies the specular color of the new DAGeometry object. The specular color is the color of the specular reflection. Matte surfaces tend to reflect the light without shifting its color, and you generally want the specular color to be a grey-level so that it doesn't alter the color of the light source. Metallic surfaces color the reflection of the light with their surface color, and you generally set the specular color to some intensity of the diffuse color. By default, the specular color is white. The bounding box is the bounding box of the underlying geometry.
Syntax
geometryObj.SpecularColor( col )
Parameters
- col
- DAColor object that is the color.
Return Value
Returns the DAGeometry object.
Remarks
This attribute overrides previous values.
See Lights in the Programmer's Guide for more information.
SpecularExponent
DAGeometry Class
Specifies the specular exponent of a DAGeometry object. Same as SpecularExponentAnim except that the parameter is a nonanimated number (a double value).
Syntax
geometryObj.SpecularExponent( power )
Parameters
- power
- Nonanimated double value that is the specular exponent. The lowest value this should be set to is 1, which yields a broad highlight that closely resembles diffuse reflection. A value from 10 through 20 is reasonable for a moderately glossy surface, and a value of 100 yields a shiny object.
Return Value
Returns the DAGeometry object.
SpecularExponentAnim
DAGeometry Class
Specifies the specular exponent of the new DAGeometry object. The specular exponent determines the shininess of the surface. Shiny surfaces are approximated by high values and less shiny surfaces by lower values.
Syntax
geometryObj.SpecularExponentAnim( power )
Parameters
- power
- DANumber object that is the specular exponent. The lowest value this should be set to is 1, which yields a broad highlight that closely resembles diffuse reflection. A value from 10 through 20 is reasonable for a moderately glossy surface, and a value of 100 yields a shiny object.
Return Value
Returns the DAGeometry object.
Remarks
See Lights in the Programmer's Guide for more information.
TextureImage
DAGeometry Class
Creates a DAGeometry object by mapping the given image, as defined by image, to the surfaces of the original geometry. If the geometry has no surfaces, the texture is ignored. If the original geometry already has a texture, the new texture completely overlays the original. Texture maps have no effect when applied to a geometry that lacks texture coordinates. By default, a geometry has no texture. The bounding box is the bounding box of the underlying geometry.
This function replaces the earlier Texture function. Texture continues to work for backward compatibility, but you should use TextureImage, which defines the texture axes more accurately.
Note You can only use TextureImage with DirectAnimation version 6.x or later.
Syntax
geometryObj.TextureImage( image )
Parameters
- image
- DAImage object.
Return Value
Returns the DAGeometry object.
Remarks
This attribute overrides previous values.
For examples of how to use TextureImage, see Solar.html and MSWorldLogo.html in the Samples\Multimedia\DAnim\JScript\Showcase directory; and see MsCubes.html in the Samples\Multimedia\DAnim\VBScript\Showcase directory.
Transform
DAGeometry Class
Creates a DAGeometry object that is the result of applying the given three-dimensional transformation to the original geometry behavior. The transformation applies to all points in the geometry, including those associated with the positions and orientations of light sources, textures, and sounds. The bounding box of a transformed geometry is the axis-aligned box enclosing the box that is the result of applying the transformation to the underlying geometry.
Syntax
geometryObj.Transform( xf )
Parameters
- xf
- DATransform3 object.
Return Value
Returns the DAGeometry object.
Remarks
This function composes values. The resulting transformation is the new value applied to the old value.
Undetectable
DAGeometry Class
Creates a new, undetectable DAGeometry object from the original geometry. An undetectable geometry means that, while the geometry is still as visible or as audible as before, any attempts to pick it are ignored.
Syntax
geometryObj.Undetectable( )
Return Value
Returns the DAGeometry object.
Remarks
The Undetectable function is useful for specifying which objects are detectable and which are not. For example, suppose a semi-transparent green sphere is used to simulate a glow around an object. Because this sphere encloses the object, the object itself would be unpickable. Instead, the pick information would always be for the sphere. Tagging the sphere as unpickable allows the object itself to be picked. This attribute overrides previous values.
DAGeometry Properties
This section contains reference material for the DAGeometry properties.
BoundingBox
DAGeometry Class
A read-only property with a DABbox3 value that creates a bounding box object defining the axis-aligned bounding box enclosing all nontransparent portions of the geometryObj.
Syntax
geometryObj.BoundingBox
Return Value
Returns the DABbox3 object.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.