Assimp  v4.1. (December 2018)
assimp::material Namespace Reference

Contains the material system which stores the imported material information. More...

Classes

struct  aiMaterial
 Data structure for a material. More...
 
struct  aiMaterialProperty
 Data structure for a single material property. More...
 
struct  aiUVTransform
 Defines how an UV channel is transformed. More...
 

Enumerations

enum  aiBlendMode : uint { Default = 0x0, Additive = 0x1 }
 Defines alpha-blend flags. More...
 
enum  aiPropertyTypeInfo : uint { Float = 0x1, String = 0x3, Integer = 0x4, Buffer = 0x5 }
 A very primitive RTTI system to store the data type of a material property. More...
 
enum  aiShadingMode : uint {
  Flat = 0x1, Gouraud = 0x2, Phong = 0x3, Blinn = 0x4,
  Toon = 0x5, OrenNayar = 0x6, Minnaert = 0x7, CookTorrance = 0x8,
  NoShading = 0x9, Fresnel = 0xa
}
 Defines all shading models supported by the library. More...
 
enum  aiTextureFlags : uint { Invert = 0x1, UseAlpha = 0x2, IgnoreAlpha = 0x4 }
 Defines some mixed flags for a particular texture. More...
 
enum  aiTextureMapMode : uint { Wrap = 0x0, Clamp = 0x1, Decal = 0x3, Mirror = 0x2 }
 Defines how UV coordinates outside the [0..1] range are handled. More...
 
enum  aiTextureMapping : uint {
  UV = 0x0, SPHERE = 0x1, CYLINDER = 0x2, BOX = 0x3,
  PLANE = 0x4, OTHER = 0x5
}
 Defines how the mapping coords for a texture are generated. More...
 
enum  aiTextureOp : uint {
  Multiply = 0x0, Add = 0x1, Subtract = 0x2, Divide = 0x3,
  SmoothAdd = 0x4, SignedAdd = 0x5
}
 Defines how the Nth texture of a specific type is combined with the result of all previous layers. More...
 
enum  aiTextureType : uint {
  NONE = 0x0, DIFFUSE = 0x1, SPECULAR = 0x2, AMBIENT = 0x3,
  EMISSIVE = 0x4, HEIGHT = 0x5, NORMALS = 0x6, SHININESS = 0x7,
  OPACITY = 0x8, DISPLACEMENT = 0x9, LIGHTMAP = 0xA, REFLECTION = 0xB,
  UNKNOWN = 0xC
}
 Defines the purpose of a texture. More...
 

Variables

const char * AI_DEFAULT_TEXTURED_MATERIAL_NAME = "TexturedDefaultMaterial"
 Default material names for meshes with UV coordinates. More...
 
const char * AI_MATKEY_BLEND_FUNC = "$mat.blend"
 ditto More...
 
const char * AI_MATKEY_BUMPSCALING = "$mat.bumpscaling"
 ditto More...
 
const char * AI_MATKEY_COLOR_AMBIENT = "$clr.ambient"
 ditto More...
 
const char * AI_MATKEY_COLOR_DIFFUSE = "$clr.diffuse"
 ditto More...
 
const char * AI_MATKEY_COLOR_EMISSIVE = "$clr.emissive"
 ditto More...
 
const char * AI_MATKEY_COLOR_REFLECTIVE = "$clr.reflective"
 ditto More...
 
const char * AI_MATKEY_COLOR_SPECULAR = "$clr.specular"
 ditto More...
 
const char * AI_MATKEY_COLOR_TRANSPARENT = "$clr.transparent"
 ditto More...
 
const char * AI_MATKEY_ENABLE_WIREFRAME = "$mat.wireframe"
 ditto More...
 
const char * AI_MATKEY_GLOBAL_BACKGROUND_IMAGE = "?bg.global"
 ditto More...
 
const char * AI_MATKEY_MAPPING = "$tex.mapping"
 ditto More...
 
const char * AI_MATKEY_MAPPINGMODE_U = "$tex.mapmodeu"
 ditto More...
 
const char * AI_MATKEY_MAPPINGMODE_V = "$tex.mapmodev"
 ditto More...
 
const char * AI_MATKEY_NAME = "?mat.name"
 Standard material property keys. More...
 
const char * AI_MATKEY_OPACITY = "$mat.opacity"
 ditto More...
 
const char * AI_MATKEY_REFLECTIVITY = "$mat.reflectivity"
 ditto More...
 
const char * AI_MATKEY_REFRACTI = "$mat.refracti"
 ditto More...
 
const char * AI_MATKEY_SHADING_MODEL = "$mat.shadingm"
 ditto More...
 
const char * AI_MATKEY_SHININESS = "$mat.shininess"
 ditto More...
 
const char * AI_MATKEY_SHININESS_STRENGTH = "$mat.shinpercent"
 ditto More...
 
const char * AI_MATKEY_TEXBLEND = "$tex.blend"
 ditto More...
 
const char * AI_MATKEY_TEXFLAGS = "$tex.flags"
 ditto More...
 
const char * AI_MATKEY_TEXMAP_AXIS = "$tex.mapaxis"
 ditto More...
 
const char * AI_MATKEY_TEXOP = "$tex.op"
 ditto More...
 
const char * AI_MATKEY_TEXTURE = "$tex.file"
 ditto More...
 
const char * AI_MATKEY_TWOSIDED = "$mat.twosided"
 
const char * AI_MATKEY_UVTRANSFORM = "$tex.uvtrafo"
 ditto More...
 
const char * AI_MATKEY_UVWSRC = "$tex.uvwsrc"
 
 C
 

Detailed Description

Contains the material system which stores the imported material information.

Enumeration Type Documentation

◆ aiBlendMode

Defines alpha-blend flags.

If you're familiar with OpenGL or D3D, these flags aren't new to you. They define how the final color value of a pixel is computed, based on the previous color at that pixel and the new color value from the material.

The basic blending formula is SourceColor * SourceBlend + DestColor * DestBlend, where DestColor is the previous color in the framebuffer at this position and SourceColor is the material color before the transparency calculation.

This corresponds to the AI_MATKEY_BLEND_FUNC property.

Enumerator
Default 

Formula: SourceColor * SourceAlpha + DestColor * (1 - SourceAlpha)

Additive 

Additive blending.

Formula: SourceColor*1 + DestColor*1

◆ aiPropertyTypeInfo

A very primitive RTTI system to store the data type of a material property.

Enumerator
Float 

Array of single-precision (32 bit) floats.

It is possible to use aiGetMaterialInteger[Array]() to query properties stored in floating-point format. The material system performs the type conversion automatically.

String 

aiString property.

Arrays of strings aren't possible, aiGetMaterialString() must be used to query a string property.

Integer 

Array of (32 bit) integers.

It is possible to use aiGetMaterialFloat[Array]() to query properties stored in integer format. The material system performs the type conversion automatically.

Buffer 

Simple binary buffer, content undefined.

Not convertible to anything.

◆ aiShadingMode

Defines all shading models supported by the library.

The list of shading modes has been taken from Blender. See Blender documentation for more information. The API does not distinguish between "specular" and "diffuse" shaders (thus the specular term for diffuse shading models like Oren-Nayar remains undefined).

Again, this value is just a hint. Assimp tries to select the shader whose most common implementation matches the original rendering results of the 3D modeller which wrote a particular model as closely as possible.

Enumerator
Flat 

Flat shading.

Shading is done on per-face base diffuse only. Also known as »faceted shading«.

Gouraud 

Simple Gouraud shading.

Phong 

Phong-Shading.

Blinn 

Phong-Blinn-Shading.

Toon 

Per-pixel toon shading.

Often referred to as »comic shading«.

OrenNayar 

Per-pixel Oren-Nayar shading.

Extension to standard Lambertian shading, taking the roughness of the material into account.

Minnaert 

Per-pixel Minnaert shading.

Extension to standard Lambertian shading, taking the "darkness" of the material into account.

CookTorrance 

Per-pixel Cook-Torrance shading.

Special shader for metallic surfaces.

NoShading 

No shading at all.

Constant light influence of 1.

Fresnel 

Fresnel shading.

◆ aiTextureFlags

Defines some mixed flags for a particular texture.

Usually you'll instruct your cg artists how textures have to look like and how they will be processed in your application. However, if you use Assimp for completely generic loading purposes you might also need to process these flags in order to display as many 'unknown' 3D models as possible correctly.

This corresponds to the AI_MATKEY_TEXFLAGS property.

Enumerator
Invert 

The texture's color values have to be inverted (i.e.

1-n component-wise).

UseAlpha 

Explicit request to the application to process the alpha channel of the texture.

Mutually exclusive with IgnoreAlpha. These flags are set if the library can say for sure that the alpha channel is used/is not used. If the model format does not define this, it is left to the application to decide whether the texture alpha channel – if any – is evaluated or not.

IgnoreAlpha 

Explicit request to the application to ignore the alpha channel of the texture.

Mutually exclusive with UseAlpha.

◆ aiTextureMapMode

Defines how UV coordinates outside the [0..1] range are handled.

Commonly referred to as 'wrapping mode'.

Enumerator
Wrap 

A texture coordinate u | v is translated to (u%1) | (v%1).

Clamp 

Texture coordinates are clamped to the nearest valid value.

Decal 

If the texture coordinates for a pixel are outside [0..1], the texture is not applied to that pixel.

Mirror 

A texture coordinate u | v becomes (u%1) | (v%1) if (u-(u%1))%2 is zero and (1-(u%1)) | (1-(v%1)) otherwise.

◆ aiTextureMapping

Defines how the mapping coords for a texture are generated.

Real-time applications typically require full UV coordinates, so the use of the aiProcess.GenUVCoords step is highly recommended. It generates proper UV channels for non-UV mapped objects, as long as an accurate description how the mapping should look like (e.g spherical) is given. See the AI_MATKEY_MAPPING property for more details.

Enumerator
UV 

The mapping coordinates are taken from an UV channel.

The AI_MATKEY_UVSRC key specifies from which (remember, meshes can have more than one UV channel).

SPHERE 

Spherical mapping.

CYLINDER 

Cylindrical mapping.

BOX 

Cubic mapping.

PLANE 

Planar mapping.

OTHER 

Undefined mapping.

◆ aiTextureOp

Defines how the Nth texture of a specific type is combined with the result of all previous layers.

Example (left: key, right: value):

 DiffColor0     - gray
DiffTextureOp0 - aiTextureOpMultiply
DiffTexture0   - tex1.png
DiffTextureOp0 - aiTextureOpAdd
DiffTexture1   - tex2.png

Written as equation, the final diffuse term for a specific pixel would be:

diffFinal = DiffColor0 * sampleTex( DiffTexture0, UV0 ) +
    sampleTex( DiffTexture1, UV0 ) * diffContrib;

where diffContrib is the intensity of the incoming light for that pixel.

Enumerator
Multiply 

T = T1 * T2

Add 

T = T1 + T2

Subtract 

T = T1 - T2

Divide 

T = T1 / T2

SmoothAdd 

T = ( T1 + T2 ) - ( T1 * T2 )

SignedAdd 

T = T1 + ( T2 - 0.5 )

◆ aiTextureType

Defines the purpose of a texture.

This is a very difficult topic. Different 3D packages support different kinds of textures. For very common texture types, such as bumpmaps, the rendering results depend on implementation details in the rendering pipelines of these applications. Assimp loads all texture references from the model file and tries to determine which of the predefined texture types below is the best choice to match the original use of the texture as closely as possible.

In content pipelines you'll usually define how textures have to be handled, and the artists working on models have to conform to this specification, regardless which 3D tool they're using.

Enumerator
NONE 

No texture, but the value to be used for aiMaterialProperty.mSemantic for all material properties not related to textures.

DIFFUSE 

The texture is combined with the result of the diffuse lighting equation.

SPECULAR 

The texture is combined with the result of the specular lighting equation.

AMBIENT 

The texture is combined with the result of the ambient lighting equation.

EMISSIVE 

The texture is added to the result of the lighting calculation.

It isn't influenced by incoming light.

HEIGHT 

The texture is a height map.

By convention, higher grey-scale values stand for higher elevations from the base height.

NORMALS 

The texture is a (tangent space) normal-map.

Again, there are several conventions for tangent-space normal maps. Assimp does (intentionally) not differenciate here.

SHININESS 

The texture defines the glossiness of the material.

The glossiness is in fact the exponent of the specular (phong) lighting equation. Usually there is a conversion function defined to map the linear color values in the texture to a suitable exponent.

OPACITY 

The texture defines per-pixel opacity.

Usually white means opaque and black means transparent.

DISPLACEMENT 

Displacement texture.

The exact purpose and format is application-dependent. Higher color values stand for higher vertex displacements.

LIGHTMAP 

Lightmap or ambient occlusion texture.

Both lightmaps and dedicated ambient occlusion maps are covered by this material property. The texture contains a scaling value for the final color value of a pixel. Its intensity is not affected by incoming light.

REFLECTION 

Reflection texture.

Contains the color of a perfect mirror reflection. Rarely used, almost never for real-time applications.

UNKNOWN 

Unknown texture.

A texture reference that does not match any of the definitions above is considered to be 'unknown'. It is still imported, but is excluded from any further postprocessing.

Variable Documentation

◆ AI_DEFAULT_TEXTURED_MATERIAL_NAME

const char* assimp::material::AI_DEFAULT_TEXTURED_MATERIAL_NAME = "TexturedDefaultMaterial"

Default material names for meshes with UV coordinates.

◆ AI_MATKEY_BLEND_FUNC

const char* assimp::material::AI_MATKEY_BLEND_FUNC = "$mat.blend"

ditto

◆ AI_MATKEY_BUMPSCALING

const char* assimp::material::AI_MATKEY_BUMPSCALING = "$mat.bumpscaling"

ditto

◆ AI_MATKEY_COLOR_AMBIENT

const char* assimp::material::AI_MATKEY_COLOR_AMBIENT = "$clr.ambient"

ditto

◆ AI_MATKEY_COLOR_DIFFUSE

const char* assimp::material::AI_MATKEY_COLOR_DIFFUSE = "$clr.diffuse"

ditto

◆ AI_MATKEY_COLOR_EMISSIVE

const char* assimp::material::AI_MATKEY_COLOR_EMISSIVE = "$clr.emissive"

ditto

◆ AI_MATKEY_COLOR_REFLECTIVE

const char* assimp::material::AI_MATKEY_COLOR_REFLECTIVE = "$clr.reflective"

ditto

◆ AI_MATKEY_COLOR_SPECULAR

const char* assimp::material::AI_MATKEY_COLOR_SPECULAR = "$clr.specular"

ditto

◆ AI_MATKEY_COLOR_TRANSPARENT

const char* assimp::material::AI_MATKEY_COLOR_TRANSPARENT = "$clr.transparent"

ditto

◆ AI_MATKEY_ENABLE_WIREFRAME

const char* assimp::material::AI_MATKEY_ENABLE_WIREFRAME = "$mat.wireframe"

ditto

◆ AI_MATKEY_GLOBAL_BACKGROUND_IMAGE

const char* assimp::material::AI_MATKEY_GLOBAL_BACKGROUND_IMAGE = "?bg.global"

ditto

◆ AI_MATKEY_MAPPING

const char* assimp::material::AI_MATKEY_MAPPING = "$tex.mapping"

ditto

◆ AI_MATKEY_MAPPINGMODE_U

const char* assimp::material::AI_MATKEY_MAPPINGMODE_U = "$tex.mapmodeu"

ditto

◆ AI_MATKEY_MAPPINGMODE_V

const char* assimp::material::AI_MATKEY_MAPPINGMODE_V = "$tex.mapmodev"

ditto

◆ AI_MATKEY_NAME

const char* assimp::material::AI_MATKEY_NAME = "?mat.name"

Standard material property keys.

Always pass 0 for texture type and index when querying these keys.

◆ AI_MATKEY_OPACITY

const char* assimp::material::AI_MATKEY_OPACITY = "$mat.opacity"

ditto

◆ AI_MATKEY_REFLECTIVITY

const char* assimp::material::AI_MATKEY_REFLECTIVITY = "$mat.reflectivity"

ditto

◆ AI_MATKEY_REFRACTI

const char* assimp::material::AI_MATKEY_REFRACTI = "$mat.refracti"

ditto

◆ AI_MATKEY_SHADING_MODEL

const char* assimp::material::AI_MATKEY_SHADING_MODEL = "$mat.shadingm"

ditto

◆ AI_MATKEY_SHININESS

const char* assimp::material::AI_MATKEY_SHININESS = "$mat.shininess"

ditto

◆ AI_MATKEY_SHININESS_STRENGTH

const char* assimp::material::AI_MATKEY_SHININESS_STRENGTH = "$mat.shinpercent"

ditto

◆ AI_MATKEY_TEXBLEND

const char* assimp::material::AI_MATKEY_TEXBLEND = "$tex.blend"

ditto

◆ AI_MATKEY_TEXFLAGS

const char* assimp::material::AI_MATKEY_TEXFLAGS = "$tex.flags"

ditto

◆ AI_MATKEY_TEXMAP_AXIS

const char* assimp::material::AI_MATKEY_TEXMAP_AXIS = "$tex.mapaxis"

ditto

◆ AI_MATKEY_TEXOP

const char* assimp::material::AI_MATKEY_TEXOP = "$tex.op"

ditto

◆ AI_MATKEY_TEXTURE

const char* assimp::material::AI_MATKEY_TEXTURE = "$tex.file"

ditto

Texture material property keys. Do not forget to specify texture type and index for these keys.

◆ AI_MATKEY_TWOSIDED

const char* assimp::material::AI_MATKEY_TWOSIDED = "$mat.twosided"

◆ AI_MATKEY_UVTRANSFORM

const char* assimp::material::AI_MATKEY_UVTRANSFORM = "$tex.uvtrafo"

ditto

◆ AI_MATKEY_UVWSRC

const char* assimp::material::AI_MATKEY_UVWSRC = "$tex.uvwsrc"

◆ C

assimp::material::C
Initial value:
{
const char* AI_DEFAULT_MATERIAL_NAME = "aiDefaultMat"
#define AI_DEFAULT_MATERIAL_NAME
Definition: material.h:58