This reference page is linked to from the following overview topics: Material and Texture Map Plug-ins, Porting Simple Material and Texture Map Plug-ins to Nitrous, Thread Safety, Plug-in Base Classes, Parameter Types, Procedural Textures Maps, Bump Mapping, Mental Ray Classes, Translation of Object Plug-ins, Supported Types.

Detailed Description

See also:: Class MtlBase, Class ShadeContext, Class UVGen, Class XYZGen, Class TexHandleMaker, Class NameAccum, Class AColor, Class Matrix3, List of Procedural Texture Clamping, Noise and Misc Functions.

Description:: This is the base class for the creation of texture map plug-ins. It provides methods for things such as calculating the color of the map for a given location, and computing a perturbation to apply to a normal for bump mapping.

Note: Developers creating procedural textures should be aware that these textures may appear less than perfect when a 3ds Max user is using the "Quick Renderer" in the Materials Editor. This is not the fault of the plug-in texture, it is simply that the "Quick Renderer" uses an algorithm that is quicker but less accurate than the standard scanline renderer. Therefore, don't be concerned if your texture does not show up perfectly when using "Quick Renderer".

Plug-In Information:: Class Defined In IMTL.H

Super Class ID TEXMAP_CLASS_ID

Standard File Name Extension DLT

Extra Include Files Needed IMTL.H (and optionally TEXUTIL.H)

Method Groups:: See Method Groups for Class Texmap.

#include <imtl.h>

Inheritance diagram for Texmap:

[legend]

List of all members.

Public Member Functions
CoreExport	Texmap ()
SClass_ID	SuperClassID ()
	Retrieves a constant representing the type of the plugin.
virtual void	GetClassName (MSTR &s)
	Retrieves the name of the plugin class.
virtual AColor	EvalColor (ShadeContext &sc)=0
virtual float	EvalMono (ShadeContext &sc)
virtual Point3	EvalNormalPerturb (ShadeContext &sc)=0
virtual BOOL	HandleOwnViewPerturb ()
virtual CoreExport BITMAPINFO *	GetVPDisplayDIB (TimeValue t, TexHandleMaker &thmaker, Interval &valid, BOOL mono=FALSE, int forceW=0, int forceH=0)
virtual void	GetUVTransform (Matrix3 &uvtrans)
virtual int	GetTextureTiling ()
virtual void	InitSlotType (int sType)
virtual int	MapSlotType (int i)
virtual int	GetUVWSource ()
virtual int	GetMapChannel ()
virtual UVGen *	GetTheUVGen ()
virtual XYZGen *	GetTheXYZGen ()
CoreExport void	RecursInitSlotType (int sType)
virtual void	SetOutputLevel (TimeValue t, float v)
virtual int	LoadMapFiles (TimeValue t)
virtual CoreExport void	RenderBitmap (TimeValue t, Bitmap *bm, float scale3D=1.0f, BOOL filter=FALSE)
CoreExport void	RefAdded (RefMakerHandle rm)
	Called after a reference is made to a target.
CoreExport SvGraphNodeReference	SvTraverseAnimGraph (IGraphObjectManager gom, Animatable owner, int id, DWORD flags)
virtual CoreExport bool	IsOutputMeaningful (ShadeContext &sc)
virtual bool	IsLocalOutputMeaningful (ShadeContext &sc)
virtual int	IsHighDynamicRange () const
Public Attributes
int	cacheID

Constructor & Destructor Documentation

CoreExport Texmap ( )

Remarks:: Constructor. The number of active uses of this texture is set to 0.

Member Function Documentation

SClass_ID SuperClassID ( ) [inline, virtual]

Search for all occurrences

Retrieves a constant representing the type of the plugin.

Returns:: A super class id that uniquely identifies the type (category) of the plugin. Note that several plugin classes can be of the same type, thus return the same super class id. Plugins are uniquely identified by their class ids. List of Super Class IDs.

See also:: SClass_ID

Reimplemented from ReferenceTarget.

{ return TEXMAP_CLASS_ID; }

virtual void GetClassName ( MSTR & s ) [inline, virtual]

Search for all occurrences

Retrieves the name of the plugin class.

This name is usually used internally for debugging purposes. For Material plug-ins this method is used to put up the material "type" name in the Material Editor.

Parameters:

s	Reference to a string filled in with the name of the plugin class

Reimplemented from ReferenceTarget.

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ s= MSTR(_M("Texture")); }

virtual AColor EvalColor ( ShadeContext & sc ) [pure virtual]

Search for all occurrences

Remarks:: This method is called to evaluate the color of the texture map for the context. This is for channels that have a color such as diffuse, specular, ambient, etc. This method is called for every pixel of the texture.

Parameters:: ShadeContext& sc

Describes the properties of the pixel to evaluate.

Returns:: An AColor object which stores the r, g, b, a values. Note: The alpha is premultiplied, and the alpha value goes into AColor::a.

Implemented in MSPluginTexmap, and MSTexmapXtnd.

virtual float EvalMono ( ShadeContext & sc ) [inline, virtual]

Search for all occurrences

Remarks:: Evaluate the map for a "mono" channel. Mono channels are those that don't have a color, but rather a single value. This is for things like shininess, transparency, etc. This just permits a bit of optimization.

Parameters:: ShadeContext& sc

Describes the properties of the pixel to evaluate.

Returns:: A floating point value for the mono channel.

Default Implementation:: {return Intens(EvalColor(sc));}

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

                                                       {
                 return Intens(EvalColor(sc));
                 }

virtual Point3 EvalNormalPerturb ( ShadeContext & sc ) [pure virtual]

Search for all occurrences

Remarks:: This method is used for bump mapping to retrieve a perturbation to apply to a normal.

Parameters:: ShadeContext& sc

Describes the properties of the pixel to evaluate.

Returns:: A deflection vector for perturbing the normal.

Implemented in MSPluginTexmap, and MSTexmapXtnd.

virtual BOOL HandleOwnViewPerturb ( ) [inline, virtual]

Search for all occurrences

Remarks:: This query is made of maps plugged into the Reflection or Refraction slots: Normally the view vector is replaced with a reflected or refracted one before calling the map: if the plugged in map doesn't need this, it should return TRUE.

Default Implementation:: { return FALSE; }

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ return FALSE; }

virtual CoreExport BITMAPINFO* GetVPDisplayDIB	(	TimeValue	t,
		TexHandleMaker &	thmaker,
		Interval &	valid,
		BOOL	mono = `FALSE`,
		int	forceW = `0`,
		int	forceH = `0`
	)		`[virtual]`

Search for all occurrences

Remarks:: This gets the viewport display bitmap in DIB format, useful when combining several maps for hardware-supported multiple texture display. If mono is TRUE, the map should do a mono evaluation and place the result in RGB. forceW and forceH, if non-zero, override dimensions specified by thmaker.

Parameters:: TimeValue t

The time to get the bitmap at.

TexHandleMaker& thmaker

This class provides methods for creating a texture handle from a 3ds Max bitmap and a Windows DIB. It also has a method to retrieve the required size of the texture map. See Class TexHandleMaker.

Interval &valid

The validity interval of the returned bitmap.

BOOL mono

Indicates whether a map should do mono evaluation.

int forceW

Overrides the bitmap width usually supplied by thmaker.

int forceH

Overrides the bitmap height usually supplied by thmaker.

Reimplemented in MSTexmapXtnd.

virtual void GetUVTransform ( Matrix3 & uvtrans ) [inline, virtual]

Search for all occurrences

Remarks:: This method is called to retrieve the UV transformation matrix for use in the viewports. If a developer is using an instance of UVGen, a method of that class may be called to retrieve the value:

(i.e. { uvGen->GetUVTransform(uvtrans); } ).

Parameters:: Matrix3 &uvtrans

The transformation matrix is returned here.

Default Implementation:: {}

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ uvtrans.IdentityMatrix(); }

virtual int GetTextureTiling ( ) [inline, virtual]

Search for all occurrences

Remarks:: This method is called to get the tiling state of the texture for use in the viewports. This is described by a set of symmetry flags that may be ORed together. If you are using an instance of UVGen to handle the UV user interface you may simply call a method of UVGen to handle this.

For example: { return uvGen->GetTextureTiling(); }

Returns:: See Texture Symmetry Flags.

Default Implementation:: { return U_WRAP|V_WRAP; }

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ return  U_WRAP|V_WRAP; }

virtual void InitSlotType ( int sType ) [inline, virtual]

Search for all occurrences

Remarks:: This method is called to initialize the slot type. This sets the proper button in the coordinate user interface rollup page. If you are using an instance of UVGen to handle the UV user interface you may simply call a method of UVGen to handle this. For example: { if (uvGen) uvGen->InitSlotType(sType); }

Parameters:: int sType

See Map Slot Types.

Default Implementation:: {}

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ defaultSlotType = sType; }

virtual int MapSlotType ( int i ) [inline, virtual]

Search for all occurrences

Remarks:: 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, texture coordinates or environment coordinates. 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 to determine the type required by the particular sub-texture. This is either texture coordinates (MAPSLOT_TEXTURE) or environment coordinates (MAPSLOT_ENVIRON).

Parameters:: int i

The index of the sub-texture whose slot type to return.

Returns:: See Map Slot Types.

Default Implementation:: { return MAPSLOT_TEXTURE; }

Reimplemented from MtlBase.

{ return defaultSlotType; }

virtual int GetUVWSource ( ) [inline, virtual]

Search for all occurrences

Remarks:: Returns a value indicating where to get the texture vertices for the Texmap.

Returns:: One of the following values:

UVWSRC_EXPLICIT

Use explicit mesh texture vertices from one of the mapping channels (see GetMapChannel() below to determine which one). This uses the UVW coordinates assigned to the object, either through the Generate Mapping Coordinates option in the object's creation parameters, or through mapping modifiers, such as UVW Map.

UVWSRC_EXPLICIT2

Use explicit mesh texture vertices from the Vertex Color Channel.

UVWSRC_OBJXYZ

Generate planar UVW mapping coordinates from the object local XYZ on-the-fly. This corresponds to the "Planar from Object XYZ" option.

UVWSRC_WORLDXYZ

This value is available in release 3.0 and later only.

Generate planar UVW mapping coordinates from the world XYZ on-the-fly. This corresponds to the "Planar From World XYZ" option. Note: this value used for the UVW is the world XYZ, taken directly, with out normalization to the objects bounding box. This differs from "Planar from Object XYZ", where the values are normalized to the object's bounding box.

Default Implementation:: { return UVWSRC_EXPLICIT; }

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ return UVWSRC_EXPLICIT; }

virtual int GetMapChannel ( ) [inline, virtual]

Search for all occurrences

Remarks:: Returns the map channel being used by the texmap if GetUVWSource() returns UVWSRC_EXPLICIT. The return value should be at least 1. A value of 0 is not acceptable.

Default Implementation:: { return 1; }

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ return 1; }   // only relevant if above returns UVWSRC_EXPLICIT

virtual UVGen* GetTheUVGen ( ) [inline, virtual]

Search for all occurrences

Remarks:: Texture maps that use a UVGen should implement this method to return a pointer to it.

Default Implementation:: { return NULL; }

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ return NULL; }  // maps with a UVGen should implement this

virtual XYZGen* GetTheXYZGen ( ) [inline, virtual]

Search for all occurrences

Remarks:: Texture maps that use a XYZGen should implement this method to return a pointer to it.

Default Implementation:: { return NULL; }

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ return NULL; } // maps with a XYZGen should implement this

CoreExport void RecursInitSlotType ( int sType )

Search for all occurrences

Remarks:: Implemented by the System.

This method is used internally to set the slot type for all subtexmaps in a tree.

virtual void SetOutputLevel	(	TimeValue	t,
		float	v
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: Sets the output level at the specified time. It is used to set the output level of the embedded Texout object, principally by importing plug-ins. It is implemented in all Texmaps.

Parameters:: TimeValue t

The time to set the output level.

float v

The value to set.

Default Implementation:: {}

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{}

virtual int LoadMapFiles ( TimeValue t ) [inline, virtual]

Search for all occurrences

Remarks:

This method is called prior to rendering to allow the plug-in to load any bitmap files it requires.

Note that LoadMapFiles() is called to load map files only, not to list the missing files. The missing files are listed using the EnumAuxFiles() method, which allows enumerating them without loading them.

Also Note: There is currently not an UnloadMapFiles() method. There are a couple of ways to do this however. One is to call Interface::FreeAllBitmaps(). That method traverses the scene reference hierarchy and calls Animatable::FreeAllBitmaps() on each item. Another approach is to evaluate the Material / TextureMap hierarchy on each material. Then call Animatable::FreeAllBitmaps() yourself in the MtlEnum::proc() shown below.

            class MtlEnum   
            {
                virtual void proc(MtlBase *m) = 0;
            };
            
            void EnumMtlTree(MtlBase *mb, MtlEnum &tenum)
            {
                tenum.proc(mb);
                for (int i=0; i<mb->NumSubTexmaps(); i++) {
                    Texmap *st = mb->GetSubTexmap(i);
                    if (st)
                        EnumMtlTree(st,tenum);
                }
                if (IsMtl(mb)) {
                    Mtl *m = (Mtl *)mb;
                    for (i=0; i<m->NumSubMtls(); i++) {
                        Mtl *sm = m->GetSubMtl(i);
                        if (sm)
                            EnumMtlTree(sm,tenum);
                    }
                }
            }

Now just define a subclass of MtlEnum that does what you want, and call EnumMtlTree. In this particular case it is more efficient than enumerating the entire reference hierarchy. If you do want to enumerate the entire reference hierarchy, here's how:

            class RefEnumProc
            {
                virtual void proc(ReferenceMaker *rm)=0;
            };
            
            void EnumRefs(ReferenceMaker *rm, RefEnumProc &proc)
            {
                proc.proc(rm);
                for (int i=0; i<rm->NumRefs(); i++) {
                    ReferenceMaker *srm = rm->GetReference(i);
                    if (srm) EnumRefs(srm,proc);
                }
            }

Just define a subclass of RefEnumProc that does what you want, and call EnumRefs on the part of the reference hierarchy you want to enumerate. For example:

            class MyEnum: public RefEnumProc
            {
                void proc(ReferenceMaker *rm) {
                    // do something ...
                }
            }
            
            void afunction(Mtl* m)
            {
                MyEnum enumer;
                EnumRefs(m,&enumer);
            }

Parameters:: TimeValue t

The time the maps are being loaded.

Returns:: Always return nonzero from this method.

Default Implementation:: { return 1; }

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

{ return 1; }

virtual CoreExport void RenderBitmap	(	TimeValue	t,
		Bitmap *	bm,
		float	scale3D = `1.0f`,
		BOOL	filter = `FALSE`
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is used to render a 2D bitmap version of this texmap.

Parameters:: TimeValue t

The time at which to render the texmap to the bitmap.

Bitmap *bm

A pointer to a bitmap to render to. This bitmap must be created at the resolution you wish to render to.

float scale3D=1.0f

This is a scale factor applied to 3D Texmaps. This is the scale of the surface in 3d space that is mapped to UV. This controls how much of the texture appears in the bitmap representation.

BOOL filter = FALSE

If TRUE the bitmap is filtered. It is quite a bit slower to rescale bitmaps with filtering on.

Remarks:: Renders the texmap to the specified bitmap.

Parameters:: TimeValue t

The time at which to render the bitmap.

Bitmap *bm

The result is stored in this bitmap. The properties of this bitmap define the resolution, color depth, etc.

float scale3D=1.0f

This is the scale of the surface in 3d space that is mapped to UV.

BOOL filter = FALSE

If TRUE the bitmap is filtered. It is quite a bit slower to rescale bitmaps with filtering on.

Default Implementation:: The default implementation calls Interface::RenderTexmap().

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

CoreExport void RefAdded ( RefMakerHandle rm ) [virtual]

Search for all occurrences

Called after a reference is made to a target.

This is called after a reference is made to this. If the target (this) needs to know that a reference to made to it, the target (this) can override this function.

Parameters:

rm	- The ReferenceMaker creating the reference.

Reimplemented from ReferenceTarget.

Reimplemented in MSPluginTexmap.

CoreExport SvGraphNodeReference SvTraverseAnimGraph	(	IGraphObjectManager *	gom,
		Animatable *	owner,
		int	id,
		DWORD	flags
	)		`[virtual]`

Search for all occurrences

Remarks:: This method is available in release 3.0 and later only.

This method traverses the graph of objects in the 3ds Max scene, adding desired objects to the schematic view. Developers can specialize this behaviour by overriding this method and adding whatever objects are interesting to the schematic view. Objects are added to the schematic view by calling IGraphObjectManager::AddAnimatable(...). Reference lines are added to the schematic view by calling IGraphObjectManager::AddReference(...). Implementers of this method should call it recursively to process other objects in the scene.

See Class IGraphObjectManager.

Parameters:

gom	Points to the schematic view window manager.
owner	The owning animatable.
id	This is usually the sub-anim number (but can actually be any value the developer chooses).
flags	See List of Schematic %View AddAnimatable Flags.

Returns:: A SvGraphNodeReference object.

Reimplemented from MtlBase.

virtual CoreExport bool IsOutputMeaningful ( ShadeContext & sc ) [virtual]

Search for all occurrences

Remarks:: Implemented by the system.

Returns true only if all submaps and itself have a meaningful output.

Returns false if at least one sub-texmap or itself does not have a meaningful output

The output of a texmap is meaningful in a given ShadeContext if it is the same as when the scene is rendered. If the map cannot determine whether the output value is the same as when rendered, it should not be meaningful. This method can be called before EvalColor() or EvalMono() on a texmap in order to decide whether to call these methods at all or if their return values should be used in further calculations.

Parameters:: ShadeContext& sc

This describes the context of the question.

Reimplemented in MSPluginTexmap, and MSTexmapXtnd.

virtual bool IsLocalOutputMeaningful ( ShadeContext & sc ) [inline, virtual]

Search for all occurrences

Remarks:: Returns TRUE if the output of this texmap is meaningful for the given context; it should not take into account subtexmaps. This method is called by IsOutputMeaningful().