## Texture

Object Hierarchy | Related C++ Class: Texture

### Inheritance

SIObject

ProjectItem

Shader

Texture

### Introduced

v3.5

### Description

The Texture object represents the current texture as specified by the OGL hardware display settings. While there may be many texture shaders in a shader tree, only the Texture object represents the current texture. You can get the current texture using Material.CurrentTexture.
The UVW values obtained from Texture.GetTransformValues are based on the current image clip (Material.CurrentImageClip) and the current UVW texture property (Material.CurrentUV).

### Methods

AddCustomOp | AddICEAttribute | AddProperty | AddScriptedOp
AddScriptedOpFromFile | AddSharedTextureLayer | AnimatedParameters2 | BelongsTo
CodePath | CodeText | CreateTextureLayer | EvaluateAt
GetAllShaders | GetICEAttributeFromName | GetPortDisplayName | GetShaderContainer
GetShaderInputType | GetShaderParameterTargets | GetShaderParameterType | GetTransformValues
HasRenderer | IsA | IsAnimated2 | IsClassOf
IsEqualTo | IsKindOf | IsLocked | IsSelected
LockOwners | PutPortDisplayName | RemoveICEAttribute | RemoveTextureLayer
RendererOptionValue | SetAsSelected | SetCapabilityFlag | SetLock
SymbolName | TaggedParameters | UnSetLock |

### Properties

AllImageClips | Application | BranchFlag | Capabilities
Categories | EvaluationID | Families | FullName
Help | HierarchicalEvaluationID | ICEAttributes | ImageClips
LockLevel | LockMasters | LockType | Model
Name | NestedObjects | ObjectID | Origin
OriginPath | OutputType | Owners | PPGLayout
Parameters | Parent | Parent3DObject | ProgID
Properties | Root | Selected | ShaderDef
ShaderType | Shaders | TextureLayers | Type

### Examples

#### 1. VBScript Example

    '
    ' This example demonstrates how to get the Texture from the object's
    ' Material once a texture projection has been applied to the object.
    '
    ' Create scene content
    NewScene , false
    set oGrid = CreatePrim( "Grid", "MeshSurface" )
    SetValue oGrid & ".polymsh.geom.subdivu", 2
    SetValue oGrid & ".polymsh.geom.subdivv", 1
    ' Put a text projection of the default image on the grid
    ApplyShader ,,,, siLetLocalMaterialsOverlap
    BlendInPresetsInsp ,,, True, True
    CreateProjection oGrid, siTxtPlanarXZ, siTxtDefaultSpherical, "Texture_Support", "Texture_Projection"
    SetInstanceDataValue , oGrid & ".Material.Phong.ambient_blend.Image.tspace_id", "Texture_Projection"
    ' You can get the texture via Material.CurrentTexture on the object
    set oMaterial = oGrid.Material
    set oTexture = oMaterial.CurrentTexture
    Application.LogMessage oTexture.FullName & " (" & TypeName(oTexture) & ")"
    ' Expected results:
    'INFO : grid.Material.Phong.ambient_blend.Image (Texture)

#### 2. VBScript Example

    'This example demonstrates how to create image textures nodes and
    'how information about them can be discovered using the Object Model.
    'In particular it shows how information about the current texture can be
    'discovered easily, but also how it is possible to find information about
    'other textures in the render tree.  The code is structures into functions
    'which can be reused in other contexts.
    set oObj = BuildDemoScene
    'There are 2 projections, 2 texture image shaders, and 2 image clips
    'But only one set acts as "current"
    logmessage "Current texture: " & oObj.Material.CurrentTexture.FullName
    logmessage "Current UV: " & oObj.Material.CurrentUV.FullName
    logmessage "Current Image Clip: " & oObj.Material.CurrentImageClip.FullName
    set oTextureShaders = FindImageTextureNodes( oObj )
    for each oTexture in oTextureShaders
            PrintImageTextureInfo oTexture, oObj
    next
    SetDisplayMode "Camera", "texturedecal"
    function BuildDemoScene
            'Creates a scene with a sphere whose material has two image textures nodes.
            'One drives the ambient of the phong and the other drives
            'the diffuse parameter.  They use two separate projections.
            ImageFile1 = XSIUtils.BuildPath( Application.InstallationPath(siFactoryPath), _
                                    "Data", _
                                    "XSI_SAMPLES",_
                                    "Pictures",_
                                    "jaiqua_face.jpg" )
            ImageFile2 = XSIUtils.BuildPath( Application.InstallationPath(siFactoryPath), _
                                    "Data", _
                                    "XSI_SAMPLES",_
                                    "Pictures",_
                                    "ehair_08.jpg" )
            set oObj = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface" )
            oObj.AddMaterial "Phong"
            dim oPhongShader, oAmbientParam, oDiffuseParam, oShinyParam
            set oPhongShader = oObj.Material.Shaders(0)
            set oAmbientParam = oPhongShader.Parameters( "ambient" )
            set oDiffuseParam = oPhongShader.Parameters( "diffuse" )
            dim oImageClip1, oImageClip2
            SICreateImageClip ImageFile1, ,oImageClip1
            SICreateImageClip ImageFile2, ,oImageClip2
            dim oImageNode1,oImageNode2
            set oImageNode1 = oAmbientParam.connectfrompreset("Image", siTextureShaderFamily)
            oImageNode1.Parameters( "tex" ).Connect( oImageClip1 )
            oImageNode1.Name = "Texture1"
            set oImageNode2 = oDiffuseParam.connectfrompreset("Image", siTextureShaderFamily)
            oImageNode2.Parameters( "tex" ).Connect( oImageClip2 )
            oImageNode2.Name = "Texture2"
            ' Connect a projection
            sProjectionName1 = "MyProjection1"
            sProjectionName2 = "MyProjection2"
            CreateProjection oObj,  siTxtSpherical, siTxtDefaultSpherical, _
                    "Texture_Support", sProjectionName1
            CreateProjection oObj,  siTxtSpherical, siTxtDefaultSpherical, _
                    "Texture_Support", sProjectionName2
            oImageNode1.Parameters("tspace_id").SetInstanceValue oObj,sProjectionName1
            oImageNode2.Parameters("tspace_id").SetInstanceValue oObj,sProjectionName2
            set BuildDemoScene = oObj
    end function
    sub PrintImageTextureInfo( oTexture, oObjectWithMaterial )
            'Display useful information about a Texture Shader node.
            'This code works even if the texture is not "current"
            logmessage "Texture:        " & oTexture
            strProjection = oTexture.Parameters("tspace_id").GetInstanceValue(oObjectWithMaterial)
            logmessage "    Projection: " & strProjection
            set oImageclip = oTexture.Parameters("tex").Source
            logmessage "    Image: " & oImageclip.FullName
            logmessage "    IsTexture: " & IsTexture( oTexture )
            bIsCurrentTexture = ( oObjectWithMaterial.Material.CurrentTexture.Name = _
                                                      oTexture.Name )
            logmessage "    Current: " & bIsCurrentTexture
            set oUVClusterProp = FindProjectionClusterProperty( oObjectWithMaterial, strProjection )
            if  typename( oUVClusterProp ) <> "Nothing" then
                    logmessage "    Projection UV Data: " & oUVClusterProp.FullName
            end if
            set oSupport = FindSupport( oObjectWithMaterial, strProjection )
            if  typename( oUVClusterProp ) <> "Nothing" then
                    logmessage "    Support: " & oSupport.FullName
            end if
    end sub
    function IsTexture(oShader)
            'Test whether an shader is a "Texture" shader
            'Note: This test returns True for Image textures, but also
            '      for procedural shaders like the fractal shader
            IsTexture = InStr( 1, oShader.Families, "Texture Shaders", 0 ) > 0
    end function
    function IsImageTexture(oShader)
            'Test more specifically whether this is an Image Shader
            'e.g. txt2d-image-explicit
            IsImageTexture= InStr( 1, oShader.ProgID, "-image", 0 ) > 0
    end function
    function FindImageTextureNodes(oObj)
            'Populate a XSICollection with all the Image Texture
            'shader nodes in the Material of the oObj argument
            'Limitations: This test only finds image nodes that are driven by an ImageClip
            'If the image is being generated (e.g. by a bumpmap generator) then
            'it will not be found.
            'Also the returned collection does not include other shaders such as Real-time shaders
            'and lens flares that might be driven by an imageclip
            set oColl = CreateObject( "XSI.Collection" )
            oColl.Unique = true
            set oImageClips = oObj.Material.ImageClips
            for each oImageClip in oImageClips
                    'The Parent property would return the Shader that uses the ImageClip
                    'However a single image clip can drive multiple Shaders.
                    'Therefore we use the Owners property.
                    'We filter out the Scene.Clips collection which is an owner
                    'of every single ImageClip.  We also filter out non-Image Textures.
                    for each oOwner in oImageClip.Owners
                            if oOwner.Type = "Shader" then
                                    if IsImageTexture( oOwner ) then
                                            oColl.Add oOwner
                                    end if
                            end if
                    next
            next
            set FindImageTextureNodes= oColl
    end function
    function FindProjectionClusterProperty( oX3DObject, strProjectionName )
            'Find the ClusterProperty associated with
            'a particular Projection used by the Material
            'of the oX3DObject argument.
            'Note: This method does not depend on Material.CurrentUV
            'so it works for any Projection
            'Normally UV data will be underneath
            'a cluster called "Texture_Coordinates_AUTO"
            'but this code searches all sample clusters
            'because the cluster might have a different name
            set oCls = oX3DObject.ActivePrimitive.Geometry._
                                    Clusters.Filter( "sample" )
            for each oCluster in oCls
                    for each oProp in oCluster.Properties
                            if oProp.Name = strProjectionName then
                                    set FindProjectionClusterProperty = oProp
                                    exit function
                            end if
                    next
            next
    end function
    function FindSupport( oX3DObject, strProjectionName )
            'Find the support object associated with a
            'particular projection for the provided X3DObject
            'It works based on the knowledge that the support
            'is nested underneath the Projection Def object,
            'which in turn is nested underneath the Projection
            'UV Data ClusterProperty
            set oUVCluster = FindProjectionClusterProperty( oX3DObject, strProjectionName )
            for each oNested in oUVCluster.NestedObjects
                    if oNested.Type = "uvprojdef" then
                            'Found the Projection Def object
                            for each oDefNested in oNested.NestedObjects
                                    if oDefNested.Type = "Texture Support" then
                                            set FindSupport = oDefNested
                                            exit function
                                    end if
                            next
                    end if
            next
    end function
    'Output of this example:
    'INFO : Current texture: sphere.Material.Phong.Texture2
    'INFO : Current UV: sphere.polymsh.cls.Texture_Coordinates_AUTO.MyProjection2
    'INFO : Current Image Clip: Clips.ehair_08_jpg
    'INFO : Texture:        Sources.Materials.DefaultLib.Material.Phong.Texture1
    'INFO :     Projection: MyProjection1
    'INFO :     Image: Sources.Materials.DefaultLib.Material.Phong.Texture1.jaiqua_face_jpg
    'INFO :     IsTexture: True
    'INFO :     Current: False
    'INFO :     Projection UV Data: sphere.polymsh.cls.Texture_Coordinates_AUTO.MyProjection1
    'INFO :     Support: Texture_Support
    'INFO : Texture:        Sources.Materials.DefaultLib.Material.Phong.Texture2
    'INFO :     Projection: MyProjection2
    'INFO :     Image: Sources.Materials.DefaultLib.Material.Phong.Texture2.ehair_08_jpg
    'INFO :     IsTexture: True
    'INFO :     Current: True
    'INFO :     Projection UV Data: sphere.polymsh.cls.Texture_Coordinates_AUTO.MyProjection2
    'INFO :     Support: Texture_Support1

### See Also

Material.CurrentTexture