Represents a texture mapping.
Properties
// The m_bCapped applies to planar, cylinder and box mappings. If m_bCapped is false, the cylinder or box is "infinite", if m_bCapped is true, they are finite. In planar mappings, m_bCapped=false means "the Z texture coordinate will always be 0.0" this is now the default behaviour in Rhino 5.0 - it's what users expect apparently.
ComponentStatus
Gets or sets the component status of the model component.
Returns ModelComponentType.TextureMapping.
Overrides: ModelComponent.ComponentType
Disposed
Indicates if this object has been disposed or the document it originally belonged to has been disposed.
HasUserData
Gets true if this class has any custom information attached to it through UserData.
The unique Id for this texture mapping object.
Overrides: ModelComponent.Id
IdIsLocked
Returns a value indicating whether the component ID is already locked.
Exceptions:
| InvalidOperationException | When setting the Index failed. This usually happens because the instance Index is already locked. |
IndexIsLocked
Returns a value indicating whether the component Index is already locked.
InstanceDefinitionModelSerialNumber
When a component is in a model as part of the information required for a linked instance definition, this value identifies the linked instance definition reference model.
Remarks: Reference components are not saved in .3dm archives. Typically this value is set and locked by the code that adds a component to a model. This value is not saved in .3dm archives.
IsComponentStatusLocked
The component status itself can be locked. This returns an indication.
IsDeleted
true if the component is deleted. Deleted components are kept by the document for undo purposes.
IsDocumentControlled
If true this object may not be modified. Any properties or functions that attempt to modify this object when it is set to "IsReadOnly" will throw a NotSupportedException.
IsReference
Gets a value indicting whether this component is a referenced component. Referenced components are part of referenced documents.
IsSystemComponent
True if this model component is a system constant.
An incomplete list of system constant model components is below:
- ON_ModelComponent::Unset
- ON_InstanceDefinition::Empty
- ON_Linetype::Unset
- ON_Linetype::Continuous
- ON_Linetype::ByLayer
- ON_Linetype::ByParent
- ON_Layer::Unset
- ON_Layer::Default
- ON_TextStyle::Unset
- ON_TextStyle::Default
- ON_TextStyle::ByLayer
- ON_TextStyle::ByParent
- ON_DimStyle::Unset
- ON_DimStyle::Default
- ON_DimStyle::DefaultInchDecimal
- ON_DimStyle::DefaultInchFractional
- ON_DimStyle::DefaultFootInchArchitecture
- ON_DimStyle::DefaultMillimeterSmall
- ON_DimStyle::DefaultMillimeterLarge
- ON_DimStyle::DefaultMillimeterArchitecture
Texture mapping type associated with this Mapping object.
ModelSerialNumber
A value identifying the model that manages this component.
Remarks: If the component is being managed by a model, this value identifies the model. In Rhino, this value is the document runtime serial number. Typically this value is set and locked by the code that adds a component to a model. This value is not saved in .3dm archives.
Exceptions:
| InvalidOperationException | When setting the Name failed. This usually happens because the instance Name is already locked. |
NameIsLocked
Returns a value indicating whether the component Name is already locked.
For primitive based mappings, these transformations are used to map the world coordinate (x,y,z) point P and surface normal N before it is projected to the normalized mapping primitive. The surface normal transformation, m_Nxyz, is always calculated from m_Pxyz. It is a runtime setting that is not saved in 3dm files. If m_type is srfp_mapping, then m_Pxyz and m_Nxyz are ignored.
obsoleteSpelling error - use PrimitiveTransform
For primitive based mappings, these transformations are used to map the world coordinate (x,y,z) point P and surface normal N before it is projected to the normalized mapping primitive. The surface normal transformation, m_Nxyz, is always calculated from m_Pxyz. It is a runtime setting that is not saved in 3dm files. If m_type is srfp_mapping, then m_Pxyz and m_Nxyz are ignored.
For primitive based mappings, these transformations are used to map the world coordinate (x,y,z) point P and surface normal N before it is projected to the normalized mapping primitive. The surface normal transformation, m_Nxyz, is always calculated from m_Pxyz. It is a runtime setting that is not saved in 3dm files. If m_type is srfp_mapping, then m_Pxyz and m_Nxyz are ignored.
ReferenceModelSerialNumber
When a component is in a model for reference, this value identifies the reference model.
Remarks: Reference components are not saved in .3dm archives. Typically this value is set and locked by the code that adds a component to a model. This value is not saved in .3dm archives.
UserData
List of custom information that is attached to this class.
UserDictionary
Dictionary of custom information attached to this class. The dictionary is actually user data provided as an easy to use shareable set of information.
Methods
ClearId
public void ClearId()
Resets the HasId property of the model component to false, if possible.
Exceptions:
| InvalidOperationException | If the ID is locked. |
ClearIndex
public void ClearIndex()
Resets the HasIndex property of the model component to false, if possible.
Exceptions:
| InvalidOperationException | If the index is locked. |
ClearName
public void ClearName()
Resets the HasName property of the model component to false, if possible.
Exceptions:
| InvalidOperationException | If the name is locked. |
ConstructConstObject
Assigns a parent object and a sub-object index to this.
public static TextureMapping CreateBoxMapping(Plane plane, Interval dx, Interval dy, Interval dz, bool capped)
Create a box projection texture mapping.
Remarks: When m_texture_space = divided, the box is mapped to texture space as follows: If the box is not capped, then each side maps to 1/4 of the texture map. v=1+---------+---------+---------+---------+ | x=dx[1] | y=dy[1] | x=dx[0] | y=dy[0] | | Front | Right | Back | Left | | --y-> | <-x-- | <-y-- | --x-> | v=0+---------+---------+---------+---------+ 0/4 <=u<= 1/4 <=u<= 2/4 <=u<= 3/4 <=u<= 4/4 If the box is capped, then each side and cap gets 1/6 of the texture map. v=1+---------+---------+---------+---------+---------+---------+ | x=dx[1] | y=dy[1] | x=dx[0] | y=dy[0] | z=dx[1] | z=dz[0] | | Front | Right | Back | Left | Top | Bottom | | --y-> | <x-- | <-y-- | --x-> | --x-> | --x-> | v=0+---------+---------+---------+---------+---------+---------+ 0/6 <=u<= 1/6 <=u<= 2/6 <=u<= 3/6 <=u<= 4/6 <=u<= 5/6 <=u<= 6/6
Parameters:
| plane (Plane) | The sides of the box the box are parallel to the plane's coordinate planes. The dx, dy, dz intervals determine the location of the sides. |
| dx (Interval) | Determines the location of the front and back planes. The vector plane.xaxis is perpendicular to these planes and they pass through plane.PointAt(dx[0],0,0) and plane.PointAt(dx[1],0,0), respectively. |
| dy (Interval) | Determines the location of the left and right planes. The vector plane.yaxis is perpendicular to these planes and they pass through plane.PointAt(0,dy[0],0) and plane.PointAt(0,dy[1],0), respectively. |
| dz (Interval) | Determines the location of the top and bottom planes. The vector plane.zaxis is perpendicular to these planes and they pass through plane.PointAt(0,0,dz[0]) and plane.PointAt(0,0,dz[1]), respectively. |
| capped (bool) | If true, the box is treated as a finite capped box. |
Returns: TextureMapping instance if input is valid
Create custom mesh mapping
Parameters:
| mesh (Mesh) | Mesh with texture coordinates |
Returns: TextureMapping instance
Create a cylindrical projection texture mapping.
Remarks: When the cylinder is capped and m_texture_space = divided, the cylinder is mapped to texture space as follows: The side is mapped to 0 <= "u" <= 2/3. The bottom is mapped to 2/3 <= "u" <= 5/6. The top is mapped to 5/6 <= "u" <= 5/6. This is the same convention box mapping uses.
Parameters:
| cylinder (Cylinder) | cylinder in world space used to define a cylindrical coordinate system. The angular parameter maps (0,2pi) to texture "u" (0,1), The height parameter maps (height[0],height[1]) to texture "v" (0,1), and the radial parameter maps (0,r) to texture "w" (0,1). |
| capped (bool) | If true, the cylinder is treated as a finite capped cylinder |
Returns: TextureMapping instance if input is valid
Create a Ocs texture mapping. Note that OCS mappings must be placed on mapping channel ON_ObjectRenderingAttributes::OCSMappingChannelId() otherwise they will not work.
Parameters:
| plane (Plane) | A plane to use for mapping. |
public static TextureMapping CreatePlaneMapping(Plane plane, Interval dx, Interval dy, Interval dz, bool capped)
Create a planar projection texture mapping
Parameters:
| plane (Plane) | A plane to use for mapping. |
| dx (Interval) | portion of the plane's x axis that is mapped to [0,1] (can be a decreasing interval) |
| dy (Interval) | portion of the plane's y axis that is mapped to [0,1] (can be a decreasing interval) |
| dz (Interval) | portion of the plane's z axis that is mapped to [0,1] (can be a decreasing interval) |
| capped (bool) | set to true if planar UVW is meant, false for planar UV |
Returns: TextureMapping instance if input is valid
Create a planar UV projection texture mapping
Parameters:
| plane (Plane) | A plane to use for mapping. |
| dx (Interval) | portion of the plane's x axis that is mapped to [0,1] (can be a decreasing interval) |
| dy (Interval) | portion of the plane's y axis that is mapped to [0,1] (can be a decreasing interval) |
| dz (Interval) | portion of the plane's z axis that is mapped to [0,1] (can be a decreasing interval) |
Returns: TextureMapping instance if input is valid
Create a spherical projection texture mapping.
Parameters:
| sphere (Sphere) | sphere in world space used to define a spherical coordinate system. The longitude parameter maps (0,2pi) to texture "u" (0,1). The latitude parameter maps (-pi/2,+pi/2) to texture "v" (0,1). The radial parameter maps (0,r) to texture "w" (0,1). |
Returns: TextureMapping instance if input is valid
Create a mapping that will convert surface parameters into normalized(0,1)x(0,1) texture coordinates.
Returns: TextureMapping instance or null if failed.
DataCRC
Increments the Cyclic Redundancy Check value by this instance.
Parameters:
| currentRemainder (uint) | The current remainder value. |
Returns: The updated remainder value.
[ConstOperation]
public void Decompose(Transform localTransform, out Vector3d xyz_position, out Vector3d xyz_scale, out Vector3d xyz_rotation, out Vector3d uvw_offset, out Vector3d uvw_repeat, out Vector3d uvw_rotation)
Gets the same decomposition of the texture mapping transforms as is used in the UI.
Dispose
public void Dispose()
Actively reclaims unmanaged resources that this instance uses.
Dispose
For derived class implementers.
This method is called with argument true when class user calls Dispose(), while with argument false when the Garbage Collector invokes the finalizer, or Finalize() method.
You must reclaim all used unmanaged resources in both cases, and can use this chance to call Dispose on disposable fields if the argument is true.
Also, you must call the base virtual method within your overriding method.
Parameters:
| disposing (bool) | true if the call comes from the Dispose() method; false if it comes from the Garbage Collector finalizer. |
EnsurePrivateCopy
public void EnsurePrivateCopy()
If you want to keep a copy of this class around by holding onto it in a variable after a command completes, call EnsurePrivateCopy to make sure that this class is not tied to the document. You can call this function as many times as you want.
Evaluate the mapping to get a texture coordinate
Parameters:
| p (Point3d) | Vertex location |
| n (Vector3d) | If the mapping projection is ray_projection, then this is the vertex unit normal. Otherwise n is ignored. |
| t (out Point3d) | Texture coordinate (u,v,w) |
| pXform (Transform) | Transformation to be applied to P before performing the mapping calculation. |
| nXform (Transform) | Transformation to be applied to N before performing the mapping calculation. One way to calculate nXxform is to use the call pXform::GetVectorTransform(nXform). |
Returns: Nonzero if evaluation is successful. When the mapping is a box or capped cylinder mapping, the value indicates which side was evaluated. Cylinder mapping: 1 = cylinder wall, 2 = bottom cap, 3 = top cap Box mapping: 1 = front, 2 = right, 3 = back, 4 = left, 5 = bottom, 6 = top
Evaluate the mapping to get a texture coordinate
Parameters:
| p (Point3d) | Vertex location |
| n (Vector3d) | If the mapping projection is ray_projection, then this is the vertex unit normal. Otherwise n is ignored. |
| t (out Point3d) | Texture coordinate (u,v,w) |
Returns: Nonzero if evaluation is successful. When the mapping is a box or capped cylinder mapping, the value indicates which side was evaluated. Cylinder mapping: 1 = cylinder wall, 2 = bottom cap, 3 = top cap Box mapping: 1 = front, 2 = right, 3 = back, 4 = left, 5 = bottom, 6 = top
GetObjectData
[SecurityPermission(SecurityAction.LinkDemand, Flags = SecurityPermissionFlag.SerializationFormatter)]
public virtual void GetObjectData(SerializationInfo info, StreamingContext context)
Populates a System.Runtime.Serialization.SerializationInfo with the data needed to serialize the target object.
Parameters:
| info (SerializationInfo) | The System.Runtime.Serialization.SerializationInfo to populate with data. |
| context (StreamingContext) | The destination (see System.Runtime.Serialization.StreamingContext) for this serialization. |
IsValidWithLog
Determines if an object is valid. Also provides a report on errors if this object happens not to be valid.
Parameters:
| log (out string) | A textual log. This out parameter is assigned during this call. |
Returns: true if this object is valid; false otherwise.
LockId
public void LockId()
Locks the component Id property.
LockIndex
public void LockIndex()
Locks the component Index property.
LockName
public void LockName()
Locks the component Name property.
NonConstOperation
protected virtual void NonConstOperation()
For derived classes implementers.
Defines the necessary implementation to free the instance from being constant.
OnSwitchToNonConst
protected virtual void OnSwitchToNonConst()
Is called when a non-constant operation first occurs.
ToJSON
Create a JSON string representation of this object
Parameters:
| options (SerializationOptions) |
ToString
Returns the name of the model component type, and then its name and index.
Remarks: This is provided as a visual aid. Do not rely on this for serialization.
Overrides: Object.ToString
public bool TryGetMappingBox(out Plane plane, out Interval dx, out Interval dy, out Interval dz, out bool capped)
Get a box projection from the texture mapping, including capped information
Remarks: Generally, GetMappingBox will not return the same parameters passed to SetBoxMapping. However, the location of the box will be the same.
Parameters:
| plane (out Plane) | The center of the box is at plane.origin and the sides of the box are parallel to the plane's coordinate planes. |
| dx (out Interval) | The "front" and "back" sides of the box are in spanned by the vectors plane.yaxis and plane.zaxis. The back plane contains the point plane.PointAt(dx[0],0,0) and the front plane contains the point plane.PointAt(dx[1],0,0). |
| dy (out Interval) | The "left" and "right" sides of the box are in spanned by the vectors plane.zaxis and plane.xaxis. The left plane contains the point plane.PointAt(0,dx[0],0) and the back plane contains the point plane.PointAt(0,dy[1],0). |
| dz (out Interval) | The "top" and "bottom" sides of the box are in spanned by the vectors plane.xaxis and plane.yaxis. The bottom plane contains the point plane.PointAt(0,0,dz[0]) and the top plane contains the point plane.PointAt(0,0,dz[1]). |
| capped (out bool) | true if box mapping is capped. |
Returns: Returns true if a valid box is returned.
Get a box projection from the texture mapping.
Remarks: Generally, GetMappingBox will not return the same parameters passed to SetBoxMapping. However, the location of the box will be the same.
Parameters:
| plane (out Plane) | The center of the box is at plane.origin and the sides of the box are parallel to the plane's coordinate planes. |
| dx (out Interval) | The "front" and "back" sides of the box are in spanned by the vectors plane.yaxis and plane.zaxis. The back plane contains the point plane.PointAt(dx[0],0,0) and the front plane contains the point plane.PointAt(dx[1],0,0). |
| dy (out Interval) | The "left" and "right" sides of the box are in spanned by the vectors plane.zaxis and plane.xaxis. The left plane contains the point plane.PointAt(0,dx[0],0) and the back plane contains the point plane.PointAt(0,dy[1],0). |
| dz (out Interval) | The "top" and "bottom" sides of the box are in spanned by the vectors plane.xaxis and plane.yaxis. The bottom plane contains the point plane.PointAt(0,0,dz[0]) and the top plane contains the point plane.PointAt(0,0,dz[1]). |
Returns: Returns true if a valid box is returned.
Get a cylindrical projection parameters from this texture mapping.
Remarks: Generally, GetMappingCylinder will not return the same parameters passed to SetCylinderMapping. However, the location of the cylinder will be the same. If this mapping is not cylindrical, the cylinder will approximate the actual mapping primitive.
Returns: Returns true if a valid cylinder is returned.
Get a cylindrical projection parameters from this texture mapping.
Remarks: Generally, GetMappingCylinder will not return the same parameters passed to SetCylinderMapping. However, the location of the cylinder will be the same. If this mapping is not cylindrical, the cylinder will approximate the actual mapping primitive.
Parameters:
| cylinder (out Cylinder) |
Returns: Returns true if a valid cylinder is returned.
Get custom mapping mesh from this texture mapping.
Parameters:
| mesh (out Mesh) |
Returns: True if custom mapping mesh was returned.
public bool TryGetMappingPlane(out Plane plane, out Interval dx, out Interval dy, out Interval dz, out bool capped)
Get plane mapping parameters from this texture mapping, including capping information
Remarks: NOTE WELL: Generally, GetMappingPlane will not return the same parameters passed to SetPlaneMapping. However, the location of the plane will be the same.
Parameters:
| plane (out Plane) | |
| dx (out Interval) | Portion of the plane's x axis that is mapped to [0,1] |
| dy (out Interval) | Portion of the plane's y axis that is mapped to [0,1] |
| dz (out Interval) | Portion of the plane's z axis that is mapped to [0,1] |
| capped (out bool) |
Returns: Return true if valid plane mapping parameters were returned.
Get plane mapping parameters from this texture mapping.
Remarks: NOTE WELL: Generally, GetMappingPlane will not return the same parameters passed to SetPlaneMapping. However, the location of the plane will be the same.
Parameters:
| plane (out Plane) | |
| dx (out Interval) | Portion of the plane's x axis that is mapped to [0,1] |
| dy (out Interval) | Portion of the plane's y axis that is mapped to [0,1] |
| dz (out Interval) | Portion of the plane's z axis that is mapped to [0,1] |
Returns: Return true if valid plane mapping parameters were returned.
Get a spherical projection parameters from this texture mapping.
Remarks: Generally, GetMappingShere will not return the same parameters passed to SetSphereMapping. However, the location of the sphere will be the same. If this mapping is not cylindrical, the cylinder will approximate the actual mapping primitive.
Parameters:
| sphere (out Sphere) | /// |
Returns: Returns true if a valid sphere is returned.