Appearance.colorTexture Property

This functionality is provided as a preview of intended future API capabilities. You are encouraged to use it and report any problems or suggestions using the Fusion API and Scripts forum.

Because this is a preview of future functionality, there is the possibility that it will change, which will possibly break any existing programs that use this functionality. Because of that, you should never deliver any programs that use any preview capabilities. For a distributed program, you should wait until it has moved from preview to released state.

Description

Path to a base-color image used as a texture for the appearance's primary color slot. Setting a non-empty path connects a fresh texture; setting an empty string disconnects the existing texture. Reading returns the connected texture's filename, or an empty string if none is connected.

Whichever of `colorTexture`, `normalTexture`, and `roughnessTexture` is set first anchors the UV scale; any of the three that are set afterward copy that scale on connect so all three maps tile at the same rate. The order matters because the underlying color and roughness textures default to a different real-world tile size than the normal-map texture, so without this alignment a typical PBR set wired through these three setters in mixed order would tile at visibly different rates.

To set a specific UV scale instead, override `texture_RealWorldScaleX` and `texture_RealWorldScaleY` on each texture via `appearanceProperties` after connecting. The same path applies for overriding wrap modes or other texture properties — access the underlying texture via `appearanceProperties.itemById('opaque_albedo').value` (or `metal_f0` / `transparent_color` depending on the appearance's surface type).

The texture image is saved inside the document, so the appearance continues to render correctly when the document is opened on another machine. The string returned by the getter, however, is the path to the image on the local file system, which after a save and re-open will typically differ from the path that was originally set. Treat the returned value as a valid path for reading the image, not as a stable identifier.

Returns false when the appearance does not host a primary color slot. Appearances created via `Appearances.add` always support this property.

Syntax

# Get the value of the property.
propertyValue = appearance_var.colorTexture

# Set the value of the property.
appearance_var.colorTexture = propertyValue

#include <Core/Materials/Appearance.h>

// Get the value of the property.
string propertyValue = appearance_var->colorTexture();

// Set the value of the property, where value_var is a string.
bool returnValue = appearance_var->colorTexture(value_var);

// Get the value of the property.
propertyValue = appearance_var.colorTexture;

// Set the value of the property.
appearance_var.colorTexture = propertyValue;

Property Value

Version