Simplygon API 7.1 User guide

Materials contain color, intensity and multi-layered textures properties for the different channels. There are a number of different standard color channels and the user is also able to create custom user channels.

From version 4.3 onwards materials in the SimplygonSDK support multi layered textures. Each channel in a Simplygon material can be composed of multiple texture layers having their own UV set. Multi layered textures for a channel are baked into a single texture while casting based on the blend function, see the casting with texture blend example.

IMaterialTable

The IMaterialTable is a collection of materials. The material table is assigned to an object. The material each part of the geometry is using is found in the array of material IDs received when calling GetMaterialIds from the geometry object.

IMaterial

The IMaterial class contains the material information. Materials are either imported alongside the object or created using the Simplygon API. They are identified by their name or index and the names are set with SetName. Channels for all commonly used PBR and non-PBR material models are pre-defined in Simplygon, and it is possible to add additional user-defined custom channels as well.

The channels can either be defined by the legacy material system, i.e. setting up a single or layered texture and basecolor in the IMaterial, by or using shading nodes to define a shading network. If a shading network has been attached to a channel, the legacy texture and basecolor set within the IMaterial object itself are ignored.

If a shading network is used, a texture table must also be defined in order to successfully use any of the Simplygon material casters.

AddUserChannel Creates user channels in the material.

TextureImage Set/get an IImageData texture to/from a material channel.

Color Sets the RGBA color for a channel.

Texture Set/get a named texture filename. When an object is exported, its material will point to the texture file.

LayeredTextureSize Set/get the size of layered textures to be used for a particular channel.

LayeredTexture Set/get the texture file name to be used for a particular channel's particular layer.

LayeredTextureLevel Set/get the UV set to be used for a particular channel's particular layer.

LayeredTextureBlendType Set/get the blend function type to be used for a particular channel's particular layer.

LayeredTextureImage Set/get the textures image data to be used for a particular channel's particular layer's texture.

ShadingNetwork Set/get a shading network that will be used instead of the defined texture path or texture image in the relevant channel.

ITextureTable

The ITextureTable is a collection of textures. This structure is used by the material casters when casting based on input materials defined by shading networks. Each texture referenced by a texture node in the shading node networks that define the input materials must be represented in this table, which is supplied to the material casters along with the material table.

ITexture

The ITexture class contains definition of a single texture. The image data can either be defined using a single file path pointing to the input image, or by setting its ImageData object directly, using the format discussed in the Image Data section. When these are added to the texture table for usage in material casting with node networks, the name, as set by SetName(), is the identifier used to correlate a texture in the shading networks with a texture in the texture table.

The Material Casting Example contains an example implementation of how to use this in a casting context properly.

Material casting

For information about casting materials see the Material Casting section.

Example
spMaterial GenerateMaterial()
{
spMaterial mat = sg->CreateMaterial();
// Add a custom user channel
mat->AddUserChannel("user_channel_name");

// The color values will be multiplied with the
// texture if there is a texture
// Preserve the diffuse texture colors
mat->SetColor(SG_MATERIAL_CHANNEL_DIFFUSE, 1.0,1.0,1.0,1.0);
// Dark specular colors, these colors will simply
// be used without a texture
mat->SetColor(SG_MATERIAL_CHANNEL_SPECULAR, 0.2,0.2,0.2,1.0);

// Generate a texture with the function from the
// previous example with IImageData objects
spImageData imgDiffuse = GenerateGradientImage(512,512);

// Place the ImageData texture in the diffuse channel
// of the material
mat->SetTextureImage(SG_MATERIAL_CHANNEL_DIFFUSE, imgDiffuse);

return mat;
}

Example
spMaterial CreateMultiLayeredMaterial()
{
pMaterial multiMaterial = sg->CreateMaterial();
// Set the number of layers the diffuse channel will use.
multiMaterial->SetLayeredTextureSize(SG_MATERIAL_CHANNEL_DIFFUSE,2);

// Import layer 0 texture (base).
spImageDataImporter imgBase = sg->CreateImageDataImporter();
imgBase->SetImportFilePath("base.jpg");
imgBase->RunImport();
// Set the material layer 0 (base texture).
multiMaterial->SetLayeredTexture(SG_MATERIAL_CHANNEL_DIFFUSE,0,"base.jpg");
multiMaterial->SetLayeredTextureLevel(SG_MATERIAL_CHANNEL_DIFFUSE,0,0);
// Set the default blend operation on the texture (color replace).
multiMaterial->SetLayeredTextureBlendType(SG_MATERIAL_CHANNEL_DIFFUSE,0,
SG_TEXTUREBLEND_REPLACE);

multiMaterial->SetLayeredTextureImage(SG_MATERIAL_CHANNEL_DIFFUSE,0,
imgBase->GetImage());
// Import diffuse layer 1 texture (add).
spImageDataImporter imagAdd = sg->CreateImageDataImporter();
imgAdd->SetImportFilePath("add.jpg");
imgAdd->RunImport();
multiMaterial->SetLayeredTexture(SG_MATERIAL_CHANNEL_DIFFUSE,1,"add.jpg");
multiMaterial->SetLayeredTextureLevel(SG_MATERIAL_CHANNEL_DIFFUSE,1,0);

// Set an additive blend operation of layer 1 texture. This layer would be
// merged into the base.
multiMaterial->SetLayeredTextureBlendType(SG_MATERIAL_CHANNEL_DIFFUSE,1,
SG_TEXTUREBLEND_ADD);

multiMaterial->SetLayeredTextureImage(SG_MATERIAL_CHANNEL_DIFFUSE,1,
imgBase->GetImage());

return multiMaterial;
}

Material Data

Material Data