Live2D Cubism Native Framework

The framework is organized into several functional components that handle different aspects of the Live2D model lifecycle and behavior:

• Model: Core functions for handling the model lifecycle, including generate, update, and destroy.
• Rendering: A renderer that implements graphics instructions to draw the model across various platforms.
• Motion: Functions for motion playback and parameter blending.
• Physics: Functions for applying transformation manipulations driven by physics to the model.
• Effect: High-level functions for adding motion information, such as automatic blinking and lip sync.
• Id: Provides unique types to manage parameter names, part names, and Drawable names set in the model.
• Math: Arithmetic functions for model manipulation and drawing, including matrix and vector calculations.
• Type: C++ type definitions used throughout the framework.
• Utils: Utility functions including a JSON parser and log output.
• Effect: Provides functions such as automatic blinking and lip sync to add motion information as an effect to the model.

The ICubismOffscreenManager<T> is a template class used to manage a pool of offscreen render targets (of type T). It handles the lifecycle of these targets, including creation, tracking their usage state, and releasing unused resources to optimize memory.

To use the manager correctly within a rendering loop, you must follow the frame lifecycle:

1. Call BeginFrameProcess() at the start of the frame.
2. Perform rendering operations using the managed render targets.
3. Call EndFrameProcess() at the end of the frame.

Key lifecycle management tasks:

• Releasing unused textures: Call ReleaseStaleRenderTextures() to free up render targets that are no longer being used, resizing the pool to the previous frame's maximum active count to prevent excessive allocation/deallocation.
• Full cleanup: Call ReleaseAllRenderTextures() to destroy all managed render targets and clear the list.

// Conceptual usage pattern
ICubismOffscreenManager<MyRenderTargetType> manager;

// Inside your render loop
manager.BeginFrameProcess();

// ... use render targets ...

manager.EndFrameProcess();
manager.ReleaseStaleRenderTextures();

The CubismModel class is the primary interface for managing a Live2D model created from MOC data. It handles the model lifecycle, parameter updates, and provides access to model data such as parts, drawables, and offscreen sources.

Key responsibilities include:

• Updating State: Call Update() to recalculate the model state based on current parameter values.
• Parameter Control: Set, add, or multiply parameter values to drive animations and expressions.
• Part & Drawable Access: Retrieve hierarchy information, opacity, and vertex data for rendering.
• Canvas Information: Access canvas dimensions and pixels per unit (PPU).
• Parameter Persistence: Use SaveParameters() and LoadParameters() to temporarily store and restore parameter values.

// Example conceptual usage
void UpdateModel(Live2D::Cubism::Framework::CubismModel& model) {
    // Set a parameter value (e.g., Eye Open)
    model.SetParameterValue(parameterId, 1.0f);
    
    // Update the model state
    model.Update();
}

In CubismJson, JSON arrays and objects are represented by the Array and Map classes, which both inherit from Value.

Array

• Accessing elements: Use the subscript operator operator[](csmInt32 index). If the index is out of bounds, it returns an error value.
• Size: Use GetSize() to get the number of elements.
• Iteration: Use GetVector() to retrieve the underlying csmVector<Value*>* for iteration.
• Adding elements: Use Add(Value* v) to append a new value.

Map (JSON Object)

• Accessing elements: Use the subscript operator operator[](const csmString& s) or operator[](const csmChar* s). If the key does not exist, it returns a NullValue.
• Keys: Use GetKeys() to retrieve a csmVector<csmString>& containing all keys in the map.
• Size: Use GetSize() to get the number of key-value pairs.
• Adding elements: Use Put(csmString& key, Value* v) to insert a new key-value pair.

// Accessing an array
Value& list = root["Elements"];
if (list.IsArray()) {
    csmInt32 size = list.GetSize();
    for (csmInt32 i = 0; i < size; ++i) {
        Value& item = list[i];
        // Process item
    }
}

// Accessing a map
Value& settings = root["Settings"];
if (settings.IsMap()) {
    csmVector<csmString>& keys = settings.GetKeys();
    for (auto it = keys.Begin(); it != keys.End(); ++it) {
        Value& val = settings[(*it)];
        // Process val
    }
}

To control how the camera moves and scales, you must set the logical coordinate boundaries and scale constraints on the CubismViewMatrix instance.

Setting Boundaries

• SetScreenRect(left, right, bottom, top): Sets the range of logical coordinates currently visible on the device.
• SetMaxScreenRect(left, right, bottom, top): Sets the maximum movable range for the camera.

Setting Scale Limits

• SetMaxScale(maxScale): Sets the maximum allowed scaling factor.
• SetMinScale(minScale): Sets the minimum allowed scaling factor.

Querying State

• Use IsMaxScale() and IsMinScale() to check if the current scale has reached its limits.
• Use GetScreenLeft(), GetScreenRight(), GetScreenBottom(), and GetScreenTop() to retrieve the current visible rectangle.
• Use GetMaxLeft(), GetMaxRight(), GetMaxBottom(), and GetMaxTop() to retrieve the maximum movable boundaries.