Initialization and Termination of Framework (Native)

Updated: 12/20/2018

Launch

Set options regarding memory allocator and logging in the CubismFramework::StartUp function.
If the memory allocator is not set, the CubismFramework::Initialize function to be performed later will not work.

// C++
LAppAllocator                  cubismAllocator;  // LAppAllocator inherits from Csm::ICubismAllocator
Csm::CubismFramework::Option   cubismOption;

// prepare for Cubism Framework API.
cubismOption.LogFunction = LAppPal::PrintMessage;
cubismOption.LoggingLevel = Live2D::Cubism::Framework::CubismFramework::Option::LogLevel_Info;
Csm::CubismFramework::StartUp(&cubismAllocator, &cubismOption);

The first argument specifies the object for which the memory allocation method is registered.
The second argument registers the level of debugging and functions for debugging.

During initialization, Cubism Core for Native version information is displayed via debugging functions, as shown below.

[CSM][I]Live2D Cubism Core version: 03.00.0003 (50331651)

Initialization

After performing the CubismFramework::StartUp function, call the CubismFramework::Initialize function.
Always call it once before using the Framework in your application.
If it is never called, an error will occur when using the Framework.
If called in succession, the process is ignored.
However, after calling the CubismFramework::Dispose function (described below) and exiting, the initialize function can be called again to initialize it.

// C++
CubismFramework::Initialize();

Exit

Calling the CubismFramework::Dispose function releases the common part resources allocated by the Framework.
Do not call this function before calling the CubismFramework::Initialize function.
Typically, it is called when the application is terminated.
As an exception, in an environment with very little memory, you can call it to release resources when not needed or when you want to completely detach the library, and then call the CubismFramework::Initialize function again the next time you want to use it.

// C++
CubismFramework::Dispose();

Custom Memory Allocator

The Framework allows customization of memory allocation.
It is applied by using an allocator class inherited from the ICubismAllocator class as the first argument in the CubismFramework::StartUp function.

// C++
class ICubismAllocator
{
public:
    /**
     * @brief Destructor
     *
     * Destructor.
     */
    virtual ~ICubismAllocator() {}

    /**
     * @brief Allocate heap memory without alignment constraints.
     *
     * @param[in]  size   Number of bytes to allocate
     *
     * @return     Address of memory allocated on success. Otherwise, ‘0’ is returned.
     */
    virtual void* Allocate(const csmUint32 size) = 0;

    /**
     * @brief Release heap memory without alignment constraints.
     *
     * @param[in]  memory   Address of memory to be released
     *
     */
    virtual void Deallocate(void* memory) = 0;


    /**
     * @brief Allocate heap memory with alignment constraints.
     *
     * @param[in]  size       Number of bytes to allocate
     * @param[in]  alignment  Memory block alignment width
     *
     * @return     Address of memory allocated on success. Otherwise, ‘0’ is returned.
     */
    virtual void* AllocateAligned(const csmUint32 size, const csmUint32 alignment) = 0;

    /**
     * @brief Release heap memory with alignment constraints.
     *
     * @param[in]  alignedMemory Address of memory to be released 
     * 
     */ 
     virtual void DeallocateAligned(void* alignedMemory) = 0; 

};

The ICubismAllocator::Allocate and ICubismAllocator::Deallocate functions are used to allocate space for dynamic arrays, associative arrays, strings, etc. within the regular Framework.
The ICubismAllocator::AllocateAligned and ICubismAllocator::DeallocateAligned functions are used to allocate space for csmMoc and csmModel handled by the Framework.
The area allocated by the ICubismAllocator::AllocateAligned function must be aligned with the size of the second argument.
If not aligned, the model may fail to load.