Developer Guide (Version 1.12)

Using Extensions

Working with Specific Extension Classes

To work with a specific extension class, a client needs to know the extension's class name or class id and the interface(s) that the class supports. With this information, the class factory can be queried from the registry, an instance created and worked with as in the following example.

// IMyExtension.h #include <CryExtension/ICryUnknown.h> struct IMyExtension : public ICryUnknown { ... }; typedef boost::shared_ptr<IMyExtension> IMyExtensionPtr;
// in client code #include <IMyExtension.h> #include <CryExtension/CryCreateClassInstance.h> IMyExtensionPtr pMyExtension; #if 0 // create extension by class name if (CryCreateClassInstance("MyExtension", pMyExtension)) #else // create extension by class id, guaranteed to create instance of same kind if (CryCreateClassInstance(MAKE_CRYGUID(0x68c7f0e0c36446fe, 0x82a3bc01b54dc7bf), pMyExtension)) #endif { // it's safe to work with pMyExtension }
// verbose version of client code above #include <IMyExtension.h> #include <CryExtension/ICryFactory.h> #include <CryExtension/ICryFactoryRegistry.h> ICryFactoryRegistry* pReg = ...; #if 0 // search extension by class name ICryFactory* pFactory = pReg->GetFactory("MyExtension"); #else // search extension by class id, guaranteed to yield same factory as in search by class name ICryFactory* pFactory = pReg->GetFactory(MAKE_CRYGUID(0x68c7f0e0c36446fe, 0x82a3bc01b54dc7bf)); #endif if (pFactory) // see comment below { ICryUnknownPtr pUnk = pFactory->CreateClassInstance(); IMyExtensionPtr pMyExtension = cryinterface_cast<IMyExtension>(pUnk); if (pMyExtension) { // it's safe to work with pMyExtension } }

As an optimization, you can enhance the if check as follows.

if (pFactory && pFactory->ClassSupports(cryiidof<IMyExtension>())) { ...

This version of the if statement will check interface support before the extension class is instantiated. This check prevents the unnecessary (and potentially expensive) construction and destruction of extensions that are incompatible with a given interface.

Finding Extension Classes that Support a Specific Interface

To determine how many extension classes in the registry support a given interface, and to list them, clients can submit queries similar to the following.

// IMyExtension.h #include <CryExtension/ICryUnknown.h> struct IMyExtension : public ICryUnknown { ... }; // in client code #include <IMyExtension.h> #include <CryExtension/ICryFactory.h> #include <CryExtension/ICryFactoryRegistry.h> ICryFactoryRegistry* pReg = ...; size_t numFactories = 0; pReg->IterateFactories(cryiidof<IMyExtension>(), 0, numFactories); ICryFactory** pFactories = new ICryFactory*[numFactories]; pReg->IterateFactories(cryiidof<IMyExtension>(), pFactories, numFactories); ... delete [] pFactories;