COM/C++ Reference—DirectAnimation Interfaces

The Microsoft® DirectAnimation® COM/C++ Reference describes the DirectAnimation interface methods that you can access only through Component Object Model (COM). Each class in the DirectAnimation Scripting Reference has an associated COM interface, and all the methods and properties described in the Scripting Reference can also be used from COM. Thus, with COM, you can access everything in the Scripting Reference, as well as the methods listed in the COM/C++ Reference. (See Using the Scripting Reference for C++ Programming for more information.)

The DirectAnimation methods that you can only use from COM involve parameters that are either a pointer to an IUnknown interface or that are of type VARIANT. From script, you can't access IUnknown and you can only use safe arrays. (A safe array is an array that contains information about the number of dimensions and the bounds of its dimensions.)

For programming information, see Using DirectAnimation from C++.

The reference is organized alphabetically, by interface.

Interfaces that contain a "2", such as IDA2Geometry, inherit from and extend the earlier interface without the "2", such as IDAGeometry.

Using DirectAnimation from C++

Using COM involves a lot of overhead in terms of reference counting, result checking, and object release handling. In general, using the COM interfaces is easier if you use the Visual C++ #import directive, which eliminates the overhead code.

For example, consider the following two pieces of code that import two images, overlay them, and display the result. One uses #import and the other does not. You can see the difference.

As you can see, the easiest way to use DirectAnimation from C++ is by including #import "danim.dll" in your header file. This wraps all the DirectAnimation objects and provides smart pointers to them as IDAObjectNamePtr; for example, IDAStaticsPtr, IDATransform3Ptr, IDAGeometryPtr, and so on. It also wraps the COM methods so that they return the [out] value, rather than returning an HRESULT with the [out] value as the method's last parameter. The wrapped PerspectiveCamera method returns a DACamera object, for example, as shown in the following code, where e is a pointer to the statics library.

IDACameraPtr cam = e->PerspectiveCamera(0.1, 0.05);

If you are using #import "danim.dll" and you want to use the unwrapped version of the methods, add the text raw_ to the beginning of the method. This will cause it to return an HRESULT, which is useful for error checking, as shown in the following code.

IDACameraPtr cam;
hr = e->raw_PerspectiveCamera(0.1, 0.05, &cam);

All of the C++ samples use #import "danim.dll" except the Movie sample in samples\multimedia\danim\c++\showcase\movie. Instead, this sample uses #include <danim.h> and uses the unwrapped methods.

When you use #import "danim.dll", and you are using the DirectAnimation control, you typically create an instance of the control in the constructor, as shown in the following code from the DragGeoCntl sample.

CDAViewerCtl::CDAViewerCtl()
    :_vc(NULL)
{
    _vc.CreateInstance(__uuidof(DAViewerControlWindowed));
    ...

You can then create the DAStatics object and use Start to start rendering the animation, as shown in the following code.

// Create the statics object
   IDAStaticsPtr e;
   e = _vc->GetMeterLibrary();
   ...
   _vc->Start();

When you use #import "danim.dll", and you are not using the DirectAnimation control (for example, when you use a Microsoft® DirectDraw® surface), you typically create an instance of the DAStatics object and DAView object when you initialize your rendering surface, as shown in the following code from the Union sample.

BOOL DXA::initDXAViewObj(IUnknown *ddsurf)
{
       IDAStaticsPtr e;

        // Create the statics object
        e.CreateInstance( L"DirectAnimation.DAStatics" );
        
        // Create and establish the view
        _view.CreateInstance( L"DirectAnimation.DAView" );
      ...

You then use StartModel to render, since you are not using the DirectAnimation control.

      _view->StartModel(model, snd, 0);

If you are not using #import "danim.dll", you need to use CoCreateInstance to create the DAStatics and DAView objects, as shown in the following code.

 BOOL DXA::initDXAViewObj(IUnknown *ddsurf)  {
    ...
	hr = CoCreateInstance(CLSID_DAView, 
	  NULL, CLSCTX_INPROC, IID_IDAView, (void**) &_view);
	if(!SUCCEEDED(hr))  {
	  cleanupDXA();
    return FALSE;
	}
	hr = CoCreateInstance(CLSID_DAStatics, 
	  NULL, CLSCTX_INPROC, IID_IDAStatics, (void**) &e);
	if(!SUCCEEDED(hr))  {
	  cleanupDXA();
    return FALSE;
	}
	...

If you use #import "danim.dll", you can access properties directly, as Black in the following example.

e->SolidColorImage(e->Black));

If you do not use #import "danim.dll", use get_PropertyName to retrieve the value of a property, as shown in the following code.

pBackClr = NULL;
hr = e->get_Black( &pBackClr );
...
if(pBackClr != NULL)  {
    pBackClr->Release();
pBackClr = NULL;
}

If you use #import "danim.dll", you can set a property directly, as shown in the following code.

_view->CompositeDirectlyToTarget = TRUE;

If you do not use #import "danim.dll", use put_PropertyName to set the value of a property, as shown in the following code.

hr = _view->put_CompositeDirectlyToTarget(TRUE);