Texture.GetTransformValues

Introduced

v3.5

Description

Calculates the UVW values based on the current OGL hardware display settings for the material. The values are read from cluster properties, and the following texture objects are used in the calculation:

- Texture projection definition

- Texture shader

- Image clip

You use bit flags to specify the texture transformation effects you want to apply. Note that some texture transformation effects are approximations. For example, GetTransformValues cannot resample the surface to create the additional sample points required by texture repeats.

C# Syntax

Object Texture.GetTransformValues( Int32 );

Scripting Syntax

oVariant = Texture.GetTransformValues( Flags );

Return Value

A Variant containing an Array of Double values. This array is in the same order as the Material.CurrentUV.

Parameters

Parameter Type Description
Flags Long siTextureEffectsComputation bit flags that specify the result of the transformation you want to compute. To apply multiple effects, add the constant values together. For example, to set all the flags, use the decimal value 127, which is the sum of all the flag constants.

Examples

1. VBScript Example

'
' This example shows how to use this Texture.GetTransformValues to bake the UVW effects directly in the cluster property
' This is done on the object material and assumes only one TextureProjection definition.
'
' Create scene content
NewScene , false
set oGrid = CreatePrim( "Grid", "MeshSurface" )
SetValue oGrid & ".polymsh.geom.subdivu", 2
SetValue oGrid & ".polymsh.geom.subdivv", 1
ApplyShader ,,,, siLetLocalMaterialsOverlap
BlendInPresetsInsp ,,, True, True
CreateProjection oGrid, siTxtPlanarXZ, siTxtDefaultSpherical, "Texture_Support", "Texture_Projection"
SetInstanceDataValue , oGrid & ".Material.Phong.ambient_blend.Image.tspace_id", "Texture_Projection"
' Set a translation in U of 0.5
SetValue oGrid & ".polymsh.cls.Texture_Coordinates_AUTO.Texture_Projection.Texture_Projection_Def.projtrsu", 0.5
' Freeze everything ;-)
FreezeCurrentUV 127
sub FreezeCurrentUV( in_lFlags )
	set oMy3DObject = Application.Selection(0)
	if TypeName(oMy3DObject) <> "X3DObject" then
		Application.LogMessage "The command won't perform it should be connected to an X3DObject"
	else
		if TypeName(oMy3DObject.ActivePrimitive.Geometry) = "PolygonMesh" then
			set oMaterial = oMy3DObject.Material
			set oClusterProperty = oMaterial.CurrentUV
			set oTexture = oMaterial.CurrentTexture
			if TypeName(oTexture) <> "Nothing" then
				aUVWValues = oTexture.GetTransformValues( in_lFlags )
				FreezeUVWValues oClusterProperty, aUVWValues
				SetDefaultValues oMaterial, oTexture, oClusterProperty, in_lflags
			else
				Application.LogMessage "There's no current texture"
			end if
		else
			Application.LogMessage "The command won't perform it should be connected to a PolygonMesh object"
		end if
	end if
end sub
' The array is already in cluster offset order
sub FreezeUVWValues(in_oClusterProperty, in_aUVWValues)
	aOLDUVWValues = in_oClusterProperty.Elements.Array
	for i = 0 to ubound(aOLDUVWValues,2)
		aOLDUVWValues(0,i) = in_aUVWValues(i*3)
		aOLDUVWValues(1,i) = in_aUVWValues(i*3 + 1)
		aOLDUVWValues(2,i) = in_aUVWValues(i*3 + 2)
	next
	in_oClusterProperty.Elements.Array = aOLDUVWValues
end sub
' Reset the default values, so to remove the actions of those effects on the
' Texture projection cluster property.
sub SetDefaultValues(in_oMaterial, in_oTexture, in_oClusterProperty, in_lflags)
	if in_lflags and siTextureComputeTransformation then
		strClusterProperty = in_oClusterProperty.FullName
		' Set translation
		SetValue strClusterProperty & ".Texture_Projection_Def.projtrsu", 0
		SetValue strClusterProperty & ".Texture_Projection_Def.projtrsv", 0
		SetValue strClusterProperty & ".Texture_Projection_Def.projtrsw", 0
		' Set scaling
		SetValue strClusterProperty & ".Texture_Projection_Def.projsclu", 1
		SetValue strClusterProperty & ".Texture_Projection_Def.projsclv", 1
		SetValue strClusterProperty & ".Texture_Projection_Def.projsclw", 1
		' Set rotation
		SetValue strClusterProperty & ".Texture_Projection_Def.projrotu", 0
		SetValue strClusterProperty & ".Texture_Projection_Def.projrotv", 0
		SetValue strClusterProperty & ".Texture_Projection_Def.projrotw", 0
	end if
	if in_lflags and siTextureComputeWrapping then
		strClusterProperty = in_oClusterProperty.FullName
		' Set wrapping
		SetValue strClusterProperty & ".Texture_Projection_Def.wrap_u", false
		SetValue strClusterProperty & ".Texture_Projection_Def.wrap_v", false
		SetValue strClusterProperty & ".Texture_Projection_Def.wrap_w", false
	end if
	if in_lflags and siTextureComputeRepeats then
		strTexture = in_oTexture.FullName
		SetValue strTexture & ".repeats.x", 1
		SetValue strTexture & ".repeats.y", 1
		SetValue strTexture & ".repeats.z", 1
	end if
	if in_lflags and siTextureComputeUVRemap then
		strTexture = in_oTexture.FullName
		SetValue strTexture & ".min.x", 0
		SetValue strTexture & ".min.y", 0
		SetValue strTexture & ".min.z", 0
		SetValue strTexture & ".max.x", 1
		SetValue strTexture & ".max.y", 1
		SetValue strTexture & ".max.z", 1
	end if
	if in_lflags and siTextureComputeAlternate then
		strTexture = in_oTexture.FullName
		SetValue strTexture & ".alt_x", 0
		SetValue strTexture & ".alt_y", 0
	end if
	if in_lflags and siTextureComputeCropping then
		set oImageClip = in_oMaterial.CurrentImageClip
		strImageClip = oImageClip.FullName
		SetValue strImageClip & ".Xmin", 0
		SetValue strImageClip & ".Ymin", 0
		SetValue strImageClip & ".Xmax", 1
		SetValue strImageClip & ".Ymax", 1
	end if
	if in_lflags and siTextureComputeFlip then
		set oImageClip = in_oMaterial.CurrentImageClip
		strImageClip = oImageClip.FullName
		SetValue strImageClip & ".FlipX", False
		SetValue strImageClip & ".FlipY", False
	end if
end sub

2. JScript Example

// This example demonstrated the relationship
// between Texture.GetTransformValues, the Texture Projection
// and the Cluster Property
var sProjectionName = "MyProjection" ;
var oCylinder = CreateCylinderWithMaterial() ;
var oCurrentTexture = oCylinder.Material.CurrentTexture ;
logmessage( "Current Texture: " + oCurrentTexture.FullName  ) ;
logmessage( "Current UV: " + oCylinder.Material.CurrentUV.FullName ) ;
logmessage( "Current ImageClip: " + oCylinder.Material.CurrentImageClip  ) ;
logmessage( "-------------Before applying a repeat----------" ) ;
PrintTransformValues( oCurrentTexture ) ;
// Now actually apply a transformation at the Texture level 
oCurrentTexture.Parameters( "repeats" ).Parameters("x").Value = 2 ;
logmessage( "-------------After applying a repeat----------" ) ;
PrintTransformValues( oCurrentTexture ) ;
// Show that the raw data was not affected
logmessage( "-------------Raw UV----------" ) ;
PrintRawProjectionData( oCylinder ) ;
SetDisplayMode("Camera", "texturedecal");
function CreateCylinderWithMaterial()
{
	// Function to create a sample scene.  It has a Cylinder
	// with a simple render tree of an image connected to a Phong.
	// To simplify the example it does not load a specific image 
	// clip so it is using the default noIcon image.
	// Create a cylinder
	newscene(null,false) ;
	var oCylinder = ActiveSceneRoot.AddGeometry( "Cylinder", "MeshSurface" ) ;
	// Reduce the size of the geometry to reduce the amount of UV values we will print out
	var oGeometryParams = GetValue( oCylinder + ".polymsh.geom" ).Parameters
	oGeometryParams("subdivu").Value = 2
	oGeometryParams("subdivv").Value = 1
	oGeometryParams("subdivbase").Value = 1
	var oMaterial = oCylinder.AddMaterial( "Phong" ) ;
	var oPhong = oMaterial.Shaders(0) 
	var oPhongParams = oPhong.Parameters ;
	// Create a texture node and connect it to both ambient and diffuse
	var oTextureShader = oPhongParams( "ambient" ).ConnectFromPreset("Image", siTextureShaderFamily) ;
	oPhongParams( "diffuse" ).Connect( oTextureShader ) ;
	// At this point the texture will not draw because there is 
	// no projection to map the 2D onto the 3D
	// This command creates the projection and the support
	CreateProjection(
			oCylinder, 
			siTxtCylindrical, 
			siTxtDefaultCylindrical, 
			"MySupport",      // Name to give new support
			sProjectionName,   // Name to give new projection
			null, 
			null, 
			null);
	// Connect the projection
	oTextureShader.Parameters("tspace_id").SetInstanceValue( oCylinder,sProjectionName ) ;
	return oCylinder ;
}
function PrintRawProjectionData( in_oObj )
{
	// Find the ClusterProperty that contains the raw UVW values 
	// of the current texture
	var oTextureClusterProperty = in_oObj.Material.CurrentUV ;
	PrintUVWClusterProperty( oTextureClusterProperty ) ;
}
function PrintUVWClusterProperty( in_oTextureClusterProperty )
{
	// Print the UVW cluster property.  It shows how to read
	// the 2-Dimensional data with JScript VBArray object
	logmessage( "Contents of " + in_oTextureClusterProperty.FullName ) ;
	var aRawUVValues = new VBArray( in_oTextureClusterProperty.Elements.Array ) ;
	for ( i = 0 ; i <= aRawUVValues.ubound(2) ; i++ )
	{
		logmessage( "UVW["+i+"] = " 
			+ XSIRound( aRawUVValues.getItem( 0, i ), 2) + "," +
			+ XSIRound( aRawUVValues.getItem( 1, i ), 2) + "," +
			+ XSIRound( aRawUVValues.getItem( 2, i ), 2)) ;				
	}
}
function PrintTransformValues( in_oTexture )
{
	// Print the transformed UVW values associated with the texture
	// It shows how the data is structured as a flattened 1D array
	logmessage( "Fully transformed contents of " +  in_oTexture.FullName ) ;
	aTransformedTexture = new VBArray(in_oTexture.GetTransformValues(127)) ;
	// We have a 1 dimensional array, with the U,V,W values flattened
	cntItems = ( aTransformedTexture.ubound(1) + 1 ) / 3 ;
	for ( i = 0 ; i < cntItems ; i++ )
	{
		logmessage( "UVW["+i+"] = " 
			+ XSIRound( aTransformedTexture.getItem( 3*i ), 2) + "," +
			+ XSIRound( aTransformedTexture.getItem( 3*i+1 ), 2) + "," +
			+ XSIRound( aTransformedTexture.getItem( 3*i+2 ), 2)) ;
	}
}
// Output:
//
//INFO : Current Texture: cylinder.Material.Phong.Image
//INFO : Current UV: cylinder.polymsh.cls.Texture_Coordinates_AUTO.MyProjection
//INFO : Current ImageClip: Clips.noIcon_pic
//INFO : -------------Before applying a repeat----------
//INFO : Fully transformed contents of cylinder.Material.Phong.Image
//INFO : UVW[0] = 0.61,0,0
//INFO : UVW[1] = 0.25,0,0
//INFO : UVW[2] = 0.75,0,0
//...snip...
//INFO : UVW[28] = 1.25,1,0
//INFO : UVW[29] = 0.75,1,0
//INFO : -------------After applying a repeat----------
//INFO : Fully transformed contents of cylinder.Material.Phong.Image
//INFO : UVW[0] = 1.23,0,0
//INFO : UVW[1] = 0.5,0,0
//INFO : UVW[2] = 1.5,0,0
//...snip...
//INFO : UVW[28] = 1.5,1,0
//INFO : UVW[29] = 0.5,1,0
//INFO : -------------Raw UV----------
//INFO : Contents of cylinder.polymsh.cls.Texture_Coordinates_AUTO.MyProjection
//INFO : UVW[0] = 0.61,0,0
//INFO : UVW[1] = 0.25,0,0
//INFO : UVW[2] = 0.75,0,0
//...snip...
//INFO : UVW[28] = 1.25,1,0
//INFO : UVW[29] = 0.75,1,0

See Also

Cluster ClusterProperty ClusterElementCollection.Array