Direct3D Programming Tip #3: Use Smart Pointers

Direct3D exposes functionality through COM interface pointers. Managing the reference counts on the obtained interfaces is a common problem for new Direct3D programmers. Managing the reference count on an interface becomes trivial if you use a smart pointer wrapper class, such as CComPtr<T> or boost::shared_ptr<T> and keep in mind the ownership policies established by the smart pointer class.

In addition to managing reference counts for you, smart pointers can make your code exception safe. When an exception is thrown, if an interface pointer is held within a CComPtr declared on the stack, then its destructor will be run when the stack is unwound. The destructor for CComPtr will call IUnknown::Release on any interface pointer it holds, thus cleaning up any locally obtained resources as the exception unwinds the stack to the nearest exception handler.

CComPtr

CComPtr is a COM interface smart pointer from the ATL library. Include the file <atlbase.h> to make CComPtr accessible to your code. The documentation on MSDN describes the semantics of the class and its methods. Because CComPtr is part of the ATL library, you will need one of the commercial editions of Visual Studio .NET 2008 in order to obtain the header <atlbase.h>. However, if you are using Visual C++ Express 2008, you can use the shared_ptr smart pointer class from boost.

Obtaining Interfaces

Use CComPtr like this when you get an interface pointer from Direct3D as an out parameter:

#include <atlbase.h>

CComPtr<IDirect3DTexture9> texture;
device->CreateTexture(256, 256, 0, D3DUSAGE_WRITEONLY, D3DFMT_A8R8G8B8,
    D3DPOOL_MANAGED, &texture, 0);

Storing Interfaces

Use CComPtr like this when you are declaring a member variable:

class SpecialSurface
{
public:
    // ...

private:
    CComPtr<IDirect3DSurface9> m_surface;
};

Releasing Interfaces

When you want to release the resource held by the interface pointer, simply assign zero to it:

void Process(IDirect3DDevice9 *device)
{
    CComPtr<IDirect3DTexture9> texture;
    device->CreateTexture(256, 256, 0, D3DUSAGE_WRITEONLY, D3DFMT_A8R8G8B8,
        D3DPOOL_MANAGED, &texture, 0);

    // ... doing something with the texture here

    // explicitly release the texture before creating a new one
    texture = 0;
    device->CreateTexture(256, 256, 0, D3DUSAGE_WRITEONLY, D3DFMT_A8R8G8B8,
        D3DPOOL_MANAGED, &texture, 0);

    // 2nd created texture is released when texture variable goes out of scope
}

When To Use CComPtr

Notice above that we simply pass in the device as its underlying interface pointer. There is no need to use a smart pointer here because nothing in Process changes the lifetime of the device and nothing stores a copy of the interface pointer for later use. Simply use CComPtr in the placs where you store interface pointers or manage their lifetimes: instance data on classes, global or static variables, local interfaces created for processing in a scope and so-on.

CComPtr/Interface Association

To associate a CComPtr with an existing interface pointer, use Attach. To disassociate a CComPtr with its underlying interface pointer, use Detach. Attach should be used with Direct3DCreate9 to avoid a reference count leak:

CComPtr<IDirect3D9> d3d;
d3d.Attach(::Direct3DCreate9(D3D_SDK_VERSION));

If we had used an assignment statement:

// Don't do this!  The interface is leaked.
CComPtr<IDirect3D9> d3d = ::Direct3DCreate9(D3D_SDK_VERSION);
// Don't do this!  The interface is leaked.
CComPtr<IDirect3D9> d3d(::Direct3DCreate9(D3D_SDK_VERSION));

then the reference count would be 2 when this statement completes. That’s because the assignment operator for CComPtr calls AddRef. So we would be at a reference count of 1 when Direct3DCreate9 returns and then at 2 when the assignment operator completes. A similar situation would have arisen had we used the constructor directly.

boost::shared_ptr

The shared_ptr class from boost provides a reference counted pointer that was obtained through new. When the reference count reaches zero, the destructor calls delete on the managed pointer. This gives you .NET style reference style semantics for instances of C++ classes.

shared_ptr can be adapted for a COM interface, so that its destructor calls Release on the underlying interface pointer. The constructor for shared_ptr can take a functor that destroys the associated resource when the reference count reaches zero. In this case, the reference count is the one managed by shared_ptr instead of the underlying COM reference count managed by IUnknown. This is explained in the boost documentation.