Parameter Operation

[Last updated: 01/18/2019]

 

CubismIdHandle

To finally identify the parameters in Cubism, we need to obtain the Index, which is a sequence of parameters.
When identifying by ID, the ID, which is a string of parameters, is matched.
The Framework provides a type called CubismIdHandle to reduce the cost of computing collations.

 

Native

The actual CubismIdHandle type is a pointer type to the CubismId class, which can be obtained by the function CubismIdManager::GetId of the managing class.
Since the CubismIdManager::GetId function returns the same pointer for the same string,
if CubismIdHandles are compared with each other and have the same pointer address, they are guaranteed to be the same string.

CubismIdManager instances can be accessed with the static CubismFramework::GetIdManager function.

The value manipulation functions provide two methods of access: by Index and by CubismIdHandle.

 

Web

The actual CubismIdHandle type is an object type of the CubismId class and can be obtained by the function CubismIdManager.getId of the managing class.
Since the CubismIdManager.getId function returns the same instance for the same string,
if CubismIdHandles are compared to each other and are the same object, they are guaranteed to be the same string.

CubismIdManager instances can be accessed with the static CubismFramework.getIdManager function.

The value manipulation functions provide two methods of access: by Index and by CubismIdHandle.

 

Set parameters

Parameters are normally played back from the motion, but values can also be specified directly.
There are three types of functions to manipulate parameters, as shown below, for each method of calculating the value to be applied.

 

1. Overwrite value

CubismModel::SetParameterValue function in Native (C++) or CubismModel.setParameterValueById function in Web (TypeScript).
The first argument is the ID or index of the parameter, the second argument is the value, and the third argument is the degree of influence.
The impact can be omitted, in which case it will be 1.
For example, setting it to 0.5 would leave 50% of the previous value affected.

Example

 

 

2. Add to current value

CubismModel::AddParameterValue function in Native (C++) or CubismModel.addParameterValueById function in Web (TypeScript).
The arguments are the same as for the Native (C++) CubismModel::SetParameterValue function or the Web (TypeScript) CubismModel.setParameterValueById function.
The value set by this function is added to the value currently set for that parameter.

Example

 

 

3. Multiply by current value

CubismModel::MultiplyParameterValue function in Native (C++) or CubismModel.multiplyParameterValueById function in Web (TypeScript).
The arguments are the same as for the Native (C++) CubismModel::SetParameterValue function or the Web (TypeScript) CubismModel.setParameterValueById function.
The value set by this function is multiplied by the value currently set for that parameter.

Example

Also, use the Native(C++) CubismModel::GetParameterValue function or the Web(TypeScript) CubismModel.getParameterValueById function to get the current parameter values.

 

Specify parameters by index

There are two ways to specify parameter IDs: by ID type, which is generated from a string, or by index.
Indexing is recommended if the frequency of calls is high, since it is faster to use indexes after caching them, such as by acquiring indexes in advance.
Parameter indices can be obtained with the Native (C++) CubismModel::GetParameterIndex function or the Web (TypeScript) CubismModel.getParameterIndex function.

Example

 

 

Save and restore parameter values

To temporarily save the current parameter values of the model, use the Native (C++) CubismModel::SaveParameters function or the Web (TypeScript) CubismModel.saveParameters function.
Doing so will temporarily save all parameter values and restore them the next time you read the Native (C++) CubismModel::LoadParameters function or the Web(TypeScript) CubismModel.loadParameters function.

Example

 

 

Usage of SaveParameters and LoadParameters in LAppModel::Update

SaveParameters and LoadParameters as APIs are for saving and calling values, but
the actual LAppModel::Update function calls LoadParameter to reset to the previous status,
applied motion playback, and then executes SaveParameter.

 

The purpose of this method is to create a base for additive and multiplicative calculations
by overwriting parameters that have not been played or specified by motion playback with values prior to other operations in Update.

Without this feature, an Add to an unspecified parameter in a motion will cause the value to be added at each update, resulting in a value out of range.

Although you can create an additive/multiplicative base even if you only Load before motion playback,
the Save after motion playback allows the last state of the motion to be retained.

 

Obtaining and setting the opacity of a part

To set the opacity of a part, use the Native(C++) CubismModel::SetPartOpacity function or the Web(TypeScript) CubismModel.setPartOpacityById function.
To get the opacity of a part, use the Native(C++) CubismModel::GetPartOpacity function or the Web(TypeScript) CubismModel.getPartOpacityById function.

Example

 

 

Timing and cost of parameter application

When setting parameters, only the parameter values are rewritten and no vertex calculations are performed.
After the parameter change, the vertices are calculated by the Native (C++) CubismModel::Update function or the Web(TypeScript) CubismModel.update function, and
the model is then drawn with the CubismRenderer::DrawModel function in Native(C++) or the CubismRenderer.drawModel function in Web(TypeScript) after applying the parameters.

 

Importance of the order in which parameters are calculated

There are three types of parameter operations: overwrite, add, and multiply.
Performing the multiplication calculation first does not affect later additions or overwrites.
If the overwrite is performed last, all previous calculation results are ignored.
It is common to apply overwriting, addition, and multiplication.

In situations where it is difficult to check the calculation as a program component, etc.,
it is necessary to know which operations perform which calculations and to set the order in which components are applied in sequence.

 

We will see what code differences cause the differences in eye opening shown in the Gif above.
This is an example of applying blinking and facial expressions to the sample model “haru” included in the SDK.
As for the facial expression settings, we are playing f06.exp3.json, which opens and closes the eyes twice as wide.
Only the C++ code is posted because the only issue is the order of computation.

After the automatic blink of the overwrite operation, set the facial expression of the multiplication operation A Update\

 

After setting the facial expression of the multiplication operation, B's Update that automatically blinks the overwrite operation

 

In A, we can confirm that the eyes are wide open after blinking due to the effect of facial expression.
On the other hand, B's calculation has been overridden by blinking and reduced to standard eye opening and closing.
The nuances expressed by the model can be very different if the order of the calculations is different.

The order of calculation of motions, expressions, and functions should also be shared with the designer.

© 2010 - 2022 Live2D Inc.