Summary
The IAllocator class manages the memory allocation of certain XStream® HDVR® SDK data structures. Specifically, the server side IVolumeData class uses this to create its volume data, as well as the memory buffer used to store rendered image data. The IAllocator class ensures that allocated memory uses 16 byte alignment, due to the XStream HDVR rendering engine optimization on the Intel® SSE instruction set.
Although the XStream HDVR SDK provides its own IAllocator class, a custom memory allocation class may be implemented to replace the built-in IAllocator class if necessary for application-specific requirements. Any custom memory allocation class must observe the 16 byte alignment requirement, or the rendering engine will fail to perform correctly.
The IAllocator class is only used in the C++ Client and Server APIs.
A custom memory allocation class MUST ensure that memory is 16 byte aligned.
Defining a Custom IAllocator Class
To create a custom allocation class, define a class that inherits from and implements the interface of the IAllocator class. This class is defined in the ./APIs/C++/Headers/bcom/bcomroot.h header file in the XStream HDVR SDK distribution. An IAllocator class must define the following methods.
IAllocator::Alloc()
The IAllocator::Alloc() method allocates a memory buffer. It takes an integer input parameter designating the number of bytes to allocate. It returns a pointer to the allocated memory or NULL if it fails.
IAllocator::AllocEx()
The IAllocator::AllocEx() method allocates a memory buffer from a memory mapped file. This method takes as input parameters an integer that designates the number of bytes to allocate, and a pointer to a character string that names the memory mapped file. If it fails, it returns a pointer to the allocated memory or NULL.
For DICOM files loaded by the XStream HDVR SDK, the memory map string will be in the form "fovia_map <path to file>".
For RAW files loaded by the XStream HDVR SDK, the memory map string will be in the form "fovia_map <path to file> <slice index in file>".
IAllocator::Free()
The IAllocator::Free() method deallocates memory that has been allocated with either the IAllocator::Alloc() or IAllocator::AllocEx() methods.
Registering the Custom IAllocator Class
Once defined, the custom IAllocator class must be registered. The XStream HDVR SDK SDK will then call this custom class when using the IAllocator interface to allocate memory. The ILibrary::SetAllocator(). method is used for registration. This method takes two input parameters. The first is a member of the ENUM_HC_ALLOCATOR_PURPOSE enumeration, and designates which allocator type is being registered. The HCAP_GENERAL allocator is used to allocate volume data, the HCAP_IMAGE allocator is used to allocate image buffers, and the HCAP_MEMORY_MAPPED allocator is used to allocate buffers for memory mapped files. The second input parameter is the address of a custom IAllocator class object.
Once registered, the appropriate IAllocator derived class object will be returned by calls to ILibrary::GetAllocator().The XStream HDVR engine uses the ILibrary::GetAllocator() method internally for memory allocation tasks that require an IAllocator method.
The XStream HDVR Server API will obtain a pointer to the ILibrary object using the hdrcsrvOpenLibrary() function. This function takes as parameters the HDRCSRV_SDK_VERSION identifier that designates the SDK version, and the address of an ILibrary pointer that is set to the address of the ILibrary object.
ILibrary *pLibrary;
hdrcsrvOpenLibrary(HDRCSRV_SDK_VERSION, &pLibrary);
// Set allocator to address of allocator object.
pLibrary->SetAllocator(0, &gCustomAllocator);
The XStream HDVR Client API will obtain a pointer to the ILibrary object using the hdrcclientOpenLibrary() function. This function takes as parameters the HDRCCLIENT_SDK_VERSION identifier that designates the SDK version, and the address of an ILibrary pointer that is set to the address of the ILibrary object.
ILibrary *pLibrary;
hdrcclientOpenLibrary(HDRCCLIENT_SDK_VERSION, &pLibrary);
// Set allocator to address of allocator object.
pLibrary->SetAllocator(HCAP_GENERAL, &gCustomAllocator);
