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 AddProperty AddScriptedOp AddScriptedOpFromFile
AddSharedTextureLayer AnimatedParameters2 BelongsTo operator CodePath
CodeText CreateTextureLayer EvaluateAt GetAllShaders
GetICEAttributeFromName GetPortDisplayName GetShaderContainer GetShaderInputType
GetShaderParameterTargets GetShaderParameterType GetTransformValues HasRenderer
IsA IsAnimated2 IsClassOf operator IsEqualTo operator
IsKindOf IsLocked operator IsSelected operator LockOwners
PutPortDisplayName RemoveTextureLayer RendererOptionValue SetAsSelected operator
SetCapabilityFlag operator SetLock SymbolName TaggedParameters
UnSetLock      
       

Properties

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

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