Class UVGen
See Also: Class MtlBase, Class ShadeContext, Class MapSampler, Class Point2, Class Point3, Class Matrix3.
class UVGen : public MtlBase
Description:
Most texture maps that use UV coordinates will use an instance of this class. This class encapsulates much of the user interface functionality for setting mirroring, tiling and so on. These are the settings found in the 'Coordinate' and 'Noise' rollup pages. This class generates UV coordinates based on the results of a UV source provided by the plug-in and the user specified transformations. An instance of this class is referenced by all the 2D texture maps. All methods of this class are implemented by the system.
Methods:
The following four methods are the only ones a plug-in needs to call typically:
Prototype:
virtual AColor EvalUVMap(ShadeContext &sc, MapSampler* samp,
BOOL filter=TRUE)=0;
Remarks:
This method is called to evaluate the color of the map based on the ShadeContext. It takes into account the users selections for mirroring, tiling, noise, etc. from the UVGen rollups.
Parameters:
ShadeContext &sc
Describes the properties of the point to evaluate.
MapSampler* samp
This is a callback used to sample the map. The plug-in creates an instance of this class, and implements its methods. A pointer to the instance is passed here. The methods of the class sample the texture for a single UV coordinate.
BOOL filter=TRUE
If TRUE the texture will be filtered.
Return Value:
The result as an AColor.
Prototype:
virtual float EvalUVMapMono(ShadeContext &sc, MapSampler* samp,
BOOL filter=TRUE)=0;
Remarks:
This method is called to evaluate the value of the map based on the ShadeContext. It takes into account the users selections for mirroring, tiling, noise, etc. from the UVGen rollups.
Parameters:
ShadeContext &sc
Describes the properties of the point to evaluate.
MapSampler* samp
This is a callback used to sample the map. The plug-in creates an instance of this class, and implements its methods. A pointer to the instance is passed here. The methods of the class sample the texture for a single UV coordinate.
BOOL filter=TRUE
If TRUE the texture will be filtered.
Return Value:
The result as a float.
The following two methods are called for bump mapping to retrieve a normal perturbation. The calling sequence for these methods is shown in the sample code below. This code takes the sum of the U derivative times the U bump vector, and the V derivative times the V bump vector. The result is the normal perturbation returned from EvalNormalPerturb().
Point3 BMTex::EvalNormalPerturb(ShadeContext& sc) {
Point3 dPdu, dPdv;
if (thebm==NULL)
return Point3(0,0,0);
uvGen->GetBumpDP(sc,dPdu,dPdv); // get bump basis vectors
Point2 dM =(.01f)*uvGen->EvalDeriv(sc,&mysamp,filterType!=FILTER_NADA);
return texout->Filter(dM.x*dPdu+dM.y*dPdv);
}
Note: In the following code you'll see the 'text book' Blinn's algorithm and the 'Lazy' approach that is actually used. During testing it was determined that these two methods are visually identical. The 'Lazy' algorithm avoids the cross products however.
Point3 Gradient::EvalNormalPerturb(ShadeContext& sc) {
Point3 dPdu, dPdv;
Point2 dM = uvGen->EvalDeriv(sc,&mysamp);
uvGen->GetBumpDP(sc,dPdu,dPdv);
#if 0
// Blinn's algorithm
Point3 N = sc.Normal();
Point3 uVec = CrossProd(N,dPdv);
Point3 vVec = CrossProd(N,dPdu);
return dM.x*uVec-dM.y*vVec;
#else
// Lazy algorithm
return texout->Filter(dM.x*dPdu+dM.y*dPdv);
#endif
}
Prototype:
virtual void GetBumpDP(ShadeContext& sc, Point3& dPdu, Point3& dPdv)=0;
Remarks:
This method may be called to compute dPdu and dPdv bump basis vectors for bump mapping. These are two vector in 3D space that give you the U and V axis of the map space. This is like taking the map space into 3D space so you can determine where the U axis is and where the V axis is.
Note: In 3ds max 3.0 and later these vectors are always normalized. This change makes it so bump mapping is invariant when a Rescale World Units is performed.
See the Advanced Topics section on Working with Materials and Textures for more information on bump mapping.
Parameters:
ShadeContext& sc
Describes the properties of the point to evaluate.
Point3& dPdu, Point3& dPdv
The bump basis vectors are returned here.
Prototype:
virtual Point2 EvalDeriv(ShadeContext& sc, MapSampler* samp,
BOOL filter=TRUE)=0;
Remarks:
This gets the amount that U and V are changing. It takes into account the users selections for mirroring, tiling, noise, etc. from the UVGen rollups.
Parameters:
ShadeContext& sc
Describes the properties of the point to evaluate.
MapSampler* samp
This is a callback used to sample the map. The plug-in creates an instance of this class, and implements its methods. A pointer to the instance is passed here. The methods of the class sample the texture for a single UV coordinate.
BOOL filter=TRUE
If TRUE the texture will be filtered.
Return Value:
df/du, df/dv as a Point2.
Prototype:
virtual void GetUV(ShadeContext& sc, Point2& UV, Point2& dUV)=0;
Remarks:
This method is not normally called directly. It retrieves the UV coordinates (depending on if they are explicit, shrinked-wrapped environment, etc.) and transforms them using the offsets and noise parameters entered by the user. It does not do the mirroring or tiling. It then returns the texture coordinates and derivatives for antialiasing.
Parameters:
ShadeContext& sc
Describes the properties of the point to evaluate.
Point2& UV
The UV texture coordinates for the point.
Point2& dUV
The derivatives of UV for the point to shade. This describes how big of a range in UV space the current pixel covers.
Prototype:
virtual void GetUVTransform(Matrix3 &uvtrans)=0;
Remarks:
This method is used internally to provide information to the interactive renderer.
Prototype:
virtual int GetTextureTiling()=0;
Remarks:
This method is used internally to provide information to the interactive renderer.
Prototype:
virtual int GetUVWSource()=0;
Remarks:
This method returns the source for the texture vertices.
Return Value:
One of the following values:
UVWSRC_EXPLICIT
Use explicit mesh texture vertices from channel 1.
UVWSRC_EXPLICIT2
Use explicit mesh texture vertices from channel 2.
UVWSRC_OBJXYZ
Generate planar UVW mapping coordinates from the object XYZ on-the-fly.
Prototype:
virtual void SetUVWSource(int s)=0;
Remarks:
This method sets the source for the texture vertices.
Parameters:
int s
One of the following values:
UVWSRC_EXPLICIT
Use explicit mesh texture vertices from one of the mapping channels (as established by SetMapChannel() below).
UVWSRC_EXPLICIT2
Use explicit mesh texture vertices from the Vertex Color Channel.
UVWSRC_OBJXYZ
Generate planar UVW mapping coordinates from the object XYZ on-the-fly.
UVWSRC_WORLDXYZ
This parameter is available in release 3.0 and later only.
Generate planar uvw mapping from world xyz on-the-fly.
Prototype:
virtual void SetMapChannel(int s);
Remarks:
This method is available in release 3.0 and later only.
Sets the mapping channel used when UVWSRC_EXPLICIT is in effect.
Parameters:
int s
The mapping channel value to set.
Default Implementation:
{}
Prototype:
virtual int SymFlags()=0;
Remarks:
This method is used internally.
Prototype:
virtual void SetSymFlags(int f)=0;
Remarks:
This method is available in release 2.0 and later only.
This method is used internally.
Prototype:
virtual void SetClipFlag(BOOL b)=0;
Remarks:
This method is available in release 2.0 and later only.
This method sets the clip flag. The clip flag controls whether the U,V values passed to MapSampler by EvalUVMap() and EvalUVMapMono() are clipped to the [0..1] interval or not. It defaults to ON (i.e., clipped).
If an object is covered by a texture, and that texture repeats (is tiled), this methods can be used to tell you which tile you're in. This allows one to do something depending on which tile it is. This is done, for example, in the Bitmap texture, when 'Jitter Placement' is on, so each tile can be moved about slightly. For an example of this see \MAXSDK\SAMPLES\MATERIALS\BMTEX.CPP. If you need this information, you can just call uvGen->SetClipFlag(FALSE) (for instance in your Update() method) and then use int(u) and int(v) to get the this info. (You'd use frac(u) and frac(v) to get clipped versions of u,v. )
Parameters:
BOOL b
TRUE to clip; FALSE to not clip.
Prototype:
virtual BOOL GetClipFlag()=0;
Remarks:
This method is available in release 2.0 and later only.
This method returns the clip flag. The clip flag controls whether the U,V values passed to MapSampler by EvalUVMap() and EvalUVMapMono() are clipped to the [0..1] interval or not. It defaults to ON (i.e., clipped). See SetClipFlag() above.
Return Value:
TRUE for clipped; FALSE if not clipped.
Prototype:
virtual int GetAxis()=0;
Remarks:
This method is available in release 2.0 and later only.
Return the axis (mapping coordinate system) used.
Return Value:
One of the following values:
AXIS_UV
AXIS_VW
AXIS_WU
Prototype:
virtual void SetAxis(int ax)=0;
Remarks:
This method is available in release 2.0 and later only.
Sets the axis (mapping coordinate system) used.
Parameters:
int ax
One of the following values:
AXIS_UV
AXIS_VW
AXIS_WU
Prototype:
virtual void InitSlotType(int sType)=0;
Remarks:
Developers typically don't need to call this method. In the Coordinates rollup in the user interface for a texture map are two options. These options are Texture or Environment. The slot type is one of these two options. There are a variety of texture coordinate types. There are the type assigned to the object and the environment type (Spherical, Cylindrical, Shrink-wrap, Screen). This method is used initialize the radio button in the dialog based on the sType passed and update the drop down list.
Parameters:
int sType
One of the following values:
MAPSLOT_TEXTURE
This is either texture coordinates.
MAPSLOT_ENVIRON
Environment coordinates.
Prototype:
virtual void SetRollupOpen(BOOL open)=0;
Remarks:
This method is available in release 3.0 and later only.
Sets the UVGen rollup state to open or closed.
Parameters:
BOOL open
TRUE for open; FALSE for closed.
Prototype:
virtual BOOL GetRollupOpen()=0;
Remarks:
This method is available in release 3.0 and later only.
Returns the open or closed state of the UVGen rollup.
Return Value:
TRUE is open; FALSE is closed.