Getting Started
This article contains the following sections.
- What is DirectAnimation?
- What's New in DirectAnimation Since Version 6?
- What's New in DirectAnimation 6?
- Who Should Use DirectAnimation?
- What Do You Need to Use DirectAnimation?
- How Can You Use DirectAnimation?
- The DirectAnimation Samples
- Documentation Roadmap
What is DirectAnimation?
Microsoft® DirectX® media is a family of high-level APIs and multimedia controls that provide rich support for animation, streaming, and integration of the different media types. Microsoft® DirectAnimation® is the DirectX media component that enables you to integrate different media types (two-dimensional images, three-dimensional geometries, sounds, movies, text, and vector graphics). The media can be animated over time and integrated with user and synthetic events. Animations can be constructed for deployment on the Web or used directly within applications or stand-alone content.
DirectAnimation is a COM API and an underlying run time that different users can access in different ways. HTML authors can add multimedia and animation to their pages by using the DirectAnimation multimedia controls without programming at all. You can also animate HTML pages by using Microsoft® Visual Basic® Scripting Edition (VBScript), Microsoft® JScript® and Java applets. Finally, Java, Visual Basic, and C++ application programmers can develop Microsoft® ActiveX® controls or full applications. Thus, DirectAnimation provides multimedia tools that scale from the HTML author to the C++ programmer.
The DirectX Media Software Development Kit (SDK) provides documentation, samples, and tutorials to help users get started with DirectAnimation.
You can implement DirectAnimation by using the DirectX foundation API and Microsoft® DirectShow®. For a guide on where to find out about particular DirectShow features, see the DirectShow documentation. For more information about the DirectX foundation components, see http://www.microsoft.com/DirectX/.
Key features of the DirectAnimation API are:
- Comprehensive support for different media types. Two-dimensional (2-D) vector graphics, images and sprites, three-dimensional (3-D) geometry, video, and sound (including MIDI) are unified in a single animation API.
- A uniform time and event model that simplifies temporal coordination and interaction of the different media types. This model frees users from frame-level details and provides the foundation for supporting inherently time-based media types such as video and audio.
DirectAnimation provides services that make it easy to build high-performance animation in a variety of environments such as HTML, VBScript and JScript, Java, and Microsoft® Visual C++®. Components include multimedia controls for HTML environments and a COM-based animation library accessible from any programming or scripting language.
A set of multimedia run-time controls supply scripting access to some of the DirectAnimation API functions and libraries. The Path, Sequencer, Sprite, and Structured Graphics controls enable you to deliver impressive animation, image, and sound content over the Web with very little code. See DirectAnimation Multimedia Controls for a description of the multimedia controls and how to use them. Or see samples to view the control samples.
The following diagram shows the DirectAnimation architecture. The Microsoft Windows Media™ Player control provides an interface to some of the DirectShow API functions. The multimedia controls provide an interface to some of the DirectAnimation library. You can also access the library directly. The DirectAnimation library, in turn, uses the DirectShow API, the DirectX foundation, and certain operating-system services. SG stands for Structured Graphics control and Seq stands for the Sequencer control.
What's New in DirectAnimation Since Version 6?
DirectAnimation has added new functionality since the release of version 6. This new version of DirectAnimation is available in Microsoft Internet Explorer 5, Microsoft® Windows® 98 Second Edition, and Windows 2000.
DirectAnimation has added a version 3 to two of its interfaces, IDA3Statics and IDA3View. To take advantage of new APIs, you need to use version 3 of the interfaces. Of course, the interfaces provided in the previous release still work.
In addition, the following new methods and properties have been added.
- DAArray:
- GetElement—retrieves a behavior at the specified array index in a DAArray object.
- SetElement—adds a behavior at the specified array index to a DAArray object.
- DAColor:
- AnimateProperty—enables color properties to be animated (vary over time).
- DAGeometry:
- Billboard—creates a new DAGeometry object that is oriented in the direction of the current camera, around a specified axis.
- DAViewerControl:
- Pause—pauses the animation model by stopping the tick count and holding the current state.
- Resume—restarts the animation model after it has been paused. Sets the start time to the current time minus the paused time.
- Stop—stops the animation model.
- Tick—enables the host of the control to manually tick the animation model, rather than having the control tick itself.
- DAStatics Functions:
- SequenceArray—creates a new behavior that, when started, will play multiple DABehavior objects in the order they appear in the array. This function is a convenience for nesting sequences.
- TriMesh—creates a set of triangle meshes that you can use to construct almost any geometry.
- LinearGradientMulticolor—creates a DAImage object that is a linear fill of an array of colors at an array of positions. The positions define vertical bands from left to right.
- RadialGradientMulticolor—creates a DAImage object object that is an image of infinite size with a radial fill created from an array of colors at an array of positions in concentric circles from the image's center.
- DAStatics Properties:
- ViewTimeDelta—a read-only property with a DANumber value that is the difference between the current time sample and the last time sample, in seconds.
What's New in DirectAnimation 6?
DirectAnimation has added a version 2 of many of its interfaces, for example, IDA2Statics. To take advantage of new APIs, you need to use version 2 of the interfaces. Of course, the interfaces provided in the previous release still work.
Some of the new methods in DirectAnimation are only accessible from C++ or are most easily accessible from C++. Therefore, a new reference section has been added, the COM/C++ Reference, where you can find these methods described.
For a complete list of new properties, functions, and methods, see New Properties, Functions, and Methods.
New features and enhancements include the following:
- Extensibility—third parties can extend or customize DirectAnimation functionality through DirectX Transform objects.
- Time substitution now can be used for sequenced behaviors, and time can be run backward (except when "until" or "switcher" constructs are part of the behavior).
- UntilNotify now can be used from scripting.
- DirectAnimation takes full advantage of Microsoft® Direct3D® hardware acceleration.
- DirectAnimation provides full support for textures in DirectX files (.bmp and .ppm are the only file formats supported).
- Additional 3-D attributes include ambient color, emissive color, specular color, and specular coefficient (see AmbientColor, EmissiveColor, SpecularColor, SpecularExponentAnim, and SpecularExponent).
- Geometry behaviors now can cast shadows (see Shadow).
- Textures can be blended with the geometry's diffuse color (see BlendTextureDiffuse).
- In addition to importing files, Geometry behaviors can be constructed from a Direct3D Retained Mode visual (see ImportDirect3DRMVisual).
You can specify wrap parameters for Geometry behaviors (see ImportDirect3DRMVisualWrapped, ImportGeometryWrapped, and ImportGeometryWrappedAsync).
- The conditional construct (cond) now can be used for sounds.
- MPEG movies have better performance, especially when played below their nominal rate.
Note that to use some of the new DirectAnimation functions, you must have DirectX version 6.x or later installed. These include DAGeometry's AmbientColor, LightRangeAnim, and LightRange, and DAStatics's ImportDirect3DRMVisual, ImportDirect3DRMVisualWrapped, ImportGeometryWrapped, and ImportGeometryWrappedAsync. You will not get an error if you use these functions without DirectX 6.x. They will simply have no effect.
To use 3-D DirectX Transform effects, you must have DirectX 6.x or later installed. To use some 2-D DirectX Transform effects, you must have optional DLLs installed. You can install these by choosing "Optional Transforms" when you install the DirectX Media SDK. See Using DirectX Transform Effects for a complete list of DirectX Transform effects and what additional software, if any, is required to use each. You use DirectX Transform effects with ApplyDXTransform or ApplyDXTransformEx, and with the functions in DADXTransformResult. Instantiation of the DirectX Transform COM object will fail if you attempt to use transforms without the proper software installed.
You must have DirectX 5.x or later installed to use DAGeometry's Shadow, Lighting, and ModelClip functions. You will not get an error if you use these functions without DirectX 5.x or DirectX 6.x. They will simply have no effect.
New Properties, Functions and Methods in Version 6
The following new methods and properties have been added to DirectAnimation.
- DAArray:
- DABehavior:
- DADXTransformResult:
- DAEvent:
- DAFontStyle:
- DAGeometry:
- DAImage:
- DAImport:
- DALineStyle:
- DAModifiableBehavior:
- DAPreferences:
- DAStatics:
- DAUntilNotifier:
- DAViewerControl:
- IDADrawingSurface:
- IDA2Geometry:
- IDASite:
- IDAStatics:
- Compose2ArrayEx
- Compose3ArrayEx
- ConcatArrayEx
- CubicBSplinePathEx
- DAArrayEx
- DATupleEx
- GradientPolygonEx
- MixArrayEx
- NumberBSplineEx
- OverlayArrayEx
- Point2BSplineEx
- Point3BSplineEx
- PolydrawPathEx
- PolylineEx
- RadialGradientPolygonAnimEx
- RadialGradientPolygonEx
- Transform3x2AnimEx
- Transform4x4AnimEx
- UnionGeometryArrayEx
- UserData
- Vector2BSplineEx
- Vector3BSplineEx
- IDA2Statics:
- IDAView:
- get_ClientSite
- get_CompositeDirectlyToTarget
- get_DC
- get_IDirectDrawSurface
- get_Preferences
- get_SimulationTime
- get_Site
- get_Window
- OnFocus
- OnKey
- OnMouseButton
- OnMouseMove
- PaletteChanged
- put_ClientSite
- put_CompositeDirectlyToTarget
- put_DC
- put_IDirectDrawSurface
- put_Site
- put_Window
- QueryHitPoint
- RemoveRunningBvr
- Render
- RePaint
- SetClipRect
- SetViewport
- StartModel
- StopModel
- IDA2View:
- IDAViewSite:
Who Should Use DirectAnimation?
Like other system services such as window management or client/server frameworks, DirectAnimation functionality supports a number of applications. This documentation focuses on Internet applications.
The multimedia authoring community includes people skilled in a variety of disciplines. From graphics system programmers to creative professionals, Web developers come from many backgrounds and bring as many approaches to the task of producing multimedia for the Web.
Web multimedia developers can be grouped by the tools they use:
| Developer | Tools |
|---|---|
| Creative professional | Painting software, scanners, cameras, image editing software, sound editors |
| Web site builder | Authoring tools for HTML (Microsoft® FrontPage®, for example) |
| Script writer | JScript, VBScript, HTML source |
| Application developer | C, C++, Visual Basic, Java, SQL, Active Server, CGI scripts |
| Graphics systems programmer | Low-level languages (C, C++) and graphics APIs |
DirectAnimation serves each of these developers. The multimedia client controls are the quickest approach for enabling common applications such as sprite sequences or line drawing. The scripting interface for JScript and VBScript adds many animation features in a simple, high-level way. Finally, you can use Java or C++ (or any other COM-enabled language) to access the media and animation library with the full power of an object-oriented, compiled language.
The following table shows the typical ways different developers would access DirectAnimation.
| Developer | Accesses DirectAnimation through... |
|---|---|
| Creative professional | DirectAnimation multimedia controls |
| Web site builder | DirectAnimation multimedia controls, DirectAnimation scripting |
| Script writer | DirectAnimation scripting, DirectAnimation for Java |
| Application developer | DirectAnimation for Java, DirectAnimation scripting, and C++ |
| Graphics systems programmer | DirectAnimation through native COM, C++, DirectX foundation, and DirectShow |
What Do You Need to Use DirectAnimation?
Internet Explorer versions 4.x and 5.x contain all the software necessary to view multimedia created with DirectAnimation.
The following list shows what you need to create presentations with DirectAnimation.
- The DirectAnimation run-time library, which is part of the Internet Explorer 4.x and 5 minimal installs.
- The DirectX Media SDK, which includes DirectAnimation samples in JScript, Visual Basic Scripting Edition (VBScript), Java, and Visual Basic.
- JScript and VBScript users need only Internet Explorer 4.x to develop animations.
- Visual Basic, Java, and C++ users need the Visual Basic, Microsoft® Visual J++®, or Visual C++ environments or their equivalents. You can also use the DirectAnimation API from VBScript and JScript without compiling.
How Can You Use DirectAnimation?
You can use DirectAnimation in the following ways.
- As an inline, HTML Web animation through JScript, VBScript, or the DirectAnimation multimedia controls.
- As a Web animation in the form of a Java applet.
- As a stand-alone application or a Microsoft ActiveX® control implemented through Java, Visual Basic, or C++.
- To construct animated windowless controls.
- To animate properties of ActiveX controls.
- To load animations asynchronously and hide the load time.
You can access DirectAnimation from JScript, VBScript, Visual Basic, and C++ through the scripting (COM) interfaces directly, or you can add DirectAnimation content to your Web pages by using the DirectAnimation multimedia controls and setting parameters on these multimedia controls—that is, without programming at all. See the DirectAnimation Multimedia Controls section for more details. Using the DirectAnimation multimedia controls directly, or using JScript or VBScript, enables you to describe inline animations with HTML. Such animations can integrate with dynamic HTML by being windowless on the page (overlaying other elements such as text) or by driving the properties of other entities on the page. You can also import HTML-rendered text and use it as a texture in an animation.
For Java programmers there is a special Java binding for DirectAnimation provided on top of the COM API that takes advantage of specific Java features. For example, operations can be overloaded so that several COM methods that perform similar functions but use different parameter types are given the same name in Java.
The DirectAnimation Samples
The DirectX Media SDK includes a wide variety of samples to illustrate using DirectAnimation with the different host languages. The following categories of samples are provided for each of the host languages.
- Exercises: Illustrate the most basic use of DirectAnimation.
- Templates: Provide code that implements common DirectAnimation tasks.
- Showcases: Demonstrate the breadth of features in the system. Some of them have real-life applications, such as advertising or education.
- Tutorials: Explain step-by-step details of how to construct some Java samples. These samples include a button labeled Info on the main HTML page that launches a new instance of the browser containing the tutorial so you can read the description side-by-side with the running animation.
Documentation Roadmap
The DirectAnimation documentation is divided into several sections. To help you find the information you need, the following list describes the content of each section and when you will typically use it. For the most recent updates to this documentation, consult the Microsoft DirectX Web site at http://www.microsoft.com/DirectX/dxm/.
- Getting Started—contains general information about DirectAnimation. Use this section to orient yourself when first starting with DirectAnimation.
- Guide to Samples—contains a description of the templates, exercises, and showcase samples included with DirectAnimation. When viewing the documents as HTML, you can link directly to each sample described. This section also includes step-by-step procedures describing how to write simple JScript, VBScript, and Java code.
- Interactive Script Demos—interactive tools to help you create animated geometries, transforms, and more in JScript, see the code as you create it, then save your code in an HTML file to use later.
- DirectAnimation Multimedia Controls—contains the reference for the DirectAnimation multimedia controls as well as wizards that enable you to experiment with the multimedia controls; also contains links to the control samples.
- Programmer's Guide—contains overview articles covering basic DirectAnimation concepts such as coordinate systems, timelines, and events, plus a detailed discussion of behaviors and media types.
- DirectAnimation Scripting Reference—contains descriptions of the interfaces and methods used by JScript, VBScript, Visual Basic, and C++ users.
- DirectAnimation Java Reference—contains descriptions of the DirectAnimation Java classes and interfaces and their methods, event data, a list of default values, and a hierarchy chart.
- COM/C++ Reference - DirectAnimation Interfaces—describes the DirectAnimation interface methods that are accessible only through COM.
- Glossary—contains definitions of basic animation terms and DirectAnimation terms.
The DirectAnimation documentation does not include material on how to program in Java, C/C++, or Visual Basic. Consult the appropriate programming documentation for this information.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.