Changing filter parameters from code

Control your filters dynamically from the code

We're going to walk you through several nifty tricks you can use to change filter parameters from code, once your app is live. These can be very useful if you need to fix something quickly without making a big deal out of it by making an official update for your app.

Here I’ll use the example of an imaginary iOS app, but it’s important to know that there’s a similar API in Android too. I’m going to explain that in another post later on.

So, these are the filter parameters I'm going to be talking about:

• Changing position, rotation, and scale

• Changing Color

• Enable / Disable

• Blend shapes

• Texture

COMPONENT	PARAMETER	VALUE
MeshRenderer	Shader color	Vector4
	Shader texture	Image
	Blend shape weight	Float
Empty string ""	Position	Vector3
	Rotation	Vector3
	Scale	Vector3
	Enabled	True/false

Since v2.2.1, iOS, and macOS allow for the following node parameters to be changed also:

• Enable animation (bool)

• Alpha enable (bool)

• Depth write (bool)

• Depth test (bool)

• Blend mode (string - off, add, alpha, darken, lighten, multiply, normal, screen, linear_burn)

• Culling mode (string - off, cw, ccw)

Besides that, inside DeepAR studio, there are plenty of shaders in which you can change the parameters.

You can find these shaders by right click on DeepAR icon → Show Package Contents → Contents/Resources/shaders or you can download all shaders below.

Inside every shader folder there is a .json file which provides parameter names for uniforms and textures which can be controlled with changeParameter methods.

Download all shaders

Changing position, rotation and scale

This parameter is used to change the transform of a Game Object at runtime, so here you can change the object position, rotation or scale.

Here is the code you can use to change the mentioned parameters:

    (void)changeParameter:(NSString*)gameObject component:(NSString*)component parameter:(NSString*)parameter vector3Value:(Vector3)value;

I'll show you how to do these using the Ball Face filter example. You can find it and download it for free in our Free Filter Pack

The first thing you need to do is to open Xcode and set the parameters for changing position, rotation, and scale. To do that, you'll need to add the code for changing parameters first.

In the code there are four parameter values:

• changeParameter - the name of the Node that you want to change (can be found in the hierarchy as visible in the Studio)

• component - the internal component type, in this case, you need to leave it as an empty string

• parameter - set one of three parameters that you want to change (position, rotation or scale)

• vector3Value - set the name of the Vector3 variable

For changeParameter, we set the Node name from the Studio hierarchy. In this case, it's gonna be RootNode, because we want to change the position, rotation, and scale of the whole Game object.

There are 3 position parameters - x, y, and z. The object position can be set by changing the x and y parameters. Rotations should be written as Euler angles in degrees, so here we only change the y rotation by -30 degrees. For scale, let's reduce the size of the object to 0.7

Here's the finished code:

Now Save, Open your app, find the Ball Face filter and check the position, rotation, and scale of the object.

Changing Color

This parameter is used to change the certain color of a Game Object at runtime.

Here is the code to change the color parameter:

    (void)changeParameter:(NSString*)gameObject component:(NSString*)component parameter:(NSString*)parameter vectorValue:(Vector4)value

I'll show this on the Scuba filter example. You can find it and download it in the Free Filter Pack.

Now open Xcode and set the color-changing parameters. For that you need to add the code for changing parameters.

There are four parameter values in the code:

• changeParameter - the name of the Node that you want to change (can be found in the hierarchy as visible in the Studio)

• component - the internal component type, in this case, you need to set the string to MeshRenderer

• parameter - set the internal uniform name (you can find it in the shader files)

• vectorValue - set the name of the Vector4 variable

For changeParameter, we'll set the Node name from the Studio hierarchy. In this case, it's gonna be water quad because we want to change only the color of this quad.

For parameters, we'll set the internal uniform name, in this case, u_color. To find the name of the internal uniform, you first need to check the shader on the material. In this case, it's the Unlit Color shader. Next, go to your shader folder, find and open Unlit Color shader, and there you'll see the name of the parameter that you need to enter.

For vectorValue set the name of the Vector4 variable. Here I used newCol.

Also, you have 3 color parameters - x, y, z - red, green, and blue. And another parameter for color opacity or alpha - w parameter.

We want to change the color of the water to semi-transparent red so we'll set values like this - R: 1.0 G: 0 B: 0 A: 0.5, where the color values are in the [0-1] range.

Now again, save this and open your app. Find the Scuba filter and see how the color of the water quad changes from blue to red.

Enable or Disable Object

Let say you want to put a button in your app that enables or disables Game Object at runtime. (for example, you may want your filter character to put their glasses on or take them off). This parameter helps you to enable/disable the value. Here is the code to apply this parameter:

    (void)changeParameter:(NSString*)gameObject component:(NSString*)component parameter:(NSString*)parameter boolValue:(bool)value

I'll show you how to do this on the Lion filter example. This one can also be found in our Free Filter Pack.

Once again, open the Xcode and set the parameters. To do that you'll need to add some code.

There are four parameter values in the code:

• changeParameter - the name of the Node that you want to change (can be found in the hierarchy as visible in the Studio)

• component - the internal component type, in this case, you need to leave it as an empty string

• parameter - set the parameter to enabled or disabled

• boolValue - boolValue takes a bool value false or true

For changeParameters, we'll set the Node name. In this case, it's Mesh quad because we want to disable this quad.

For parameter, we'll set to enabled and for boolValue, we'll set false.

And again, save this, open your app, then find the Lion filter and see how you can disable this filter.

Blend Shapes

This method allows the user to change the value of blendshape parameters during runtime.

Here is the code to set this parameter:

    (void)changeParameter:(NSString*)gameObject component:(NSString*)component parameter:(NSString*)parameter floatValue:(float)value

Let's use the Beauty filter example here. You can find and download it from our Free Filter Pack.

Open Xcode and add the code to set the parameters.

There are four parameter values here:

• changeParameter - the name of the Node that you want to change (can be found in the hierarchy as visible in the Studio)

• component - the internal component type, in this case, you need to it leave as empty string

• parameter - the name of the parameter to be changed, for example, the name of the blendshape on a mesh. The parameter must exist for the component.

• floatValue - the new value to be applied to the parameter

For changeParameters we first need to set the Node name. In this case, we'll set it to faceMorphFluffy quad, because we want to change the value of blendshape in this quad.

For parameter we set the name to chin_raise, to change the size of the chin. UnderfloatValue`, let's set value to -90.0f and that'll raise the chin by 90%.

Now, save this, open your app, find the Beauty filter and see how this changes the chin size.

Texture

This method allows the user to load an image and set it as a texture during runtime. This can be useful if you want to leverage our background segmentation feature, and change the background in your filter.

Here is the code to apply this parameter:

    (void)changeParameter:(NSString*)gameObject component:(NSString*)component parameter:(NSString*)parameter image:(UIImage*)image

Let's use the Background filter example. This one's also in the Free Filter Pack.

Open Xcode and add the code to set the parameters.

Four parameter values found here:

• changeParameter - the name of the Node that you want to change (can be found in the hierarchy as visible in the Studio)

• component - the internal component type, in this case, you need to set the string to MeshRenderer

• parameter - set the internal uniform name ( internal uniform name can be found in the shader files )

• image - set the name for a variable

For changeParameters, we'll set the Node name to Background quad because we want to change the background image.

For parameters, we'll set the internal uniform name, in this case, s_texColor. To find the name of the internal uniform, first, you need to check the shader on that material. Here, that's the Unlit Texture shader. Now go to your shaders folder, find and open Unlit Texture shader, and there you'll find the name of the parameter you need to enter.

Add the image inside Xcode and set the image name in:

      UIImage* img = [UIImage imageNamed:@"image_name.jpg"];

Here we added mountain path image called mountain.jpg:

Now, save this, open your app and find the Background segmentation filter and see how this changes the background image.

Physics subsystem

Additionally, the Change Parameter API call can be used to change the physics subsystem parameters as well. More info about those parameters can be found here.