iparamb2.h File Reference

This reference page is linked to from the following overview topics:

---

#include "PB2Export.h"
#include "maxheap.h"
#include "iparamb.h"
#include "iparamm.h"
#include "assetmanagement/AssetType.h"
#include "assetmanagement/AssetId.h"
#include "iparamb2Typedefs.h"
#include "TabTypes.h"
#include "paramtype.h"

Classes
struct	PB2Value
struct	ParamAlias
class	IParamBlock2
class	PBValidator
class	PBAccessor
struct	ParamDef
class	ClassDesc2
class	ParamBlockDesc2
struct	ParamBlockDesc2::map_spec
class	ParamBlock2PLCB
class	IParamBlock2PostLoadInfo
	Informational class about ParamBlock2 objects loaded from file. More...

Namespaces
	MaxSDK
	MaxSDK::AssetManagement

Macros
#define	P_CLASS_PARAMS   0x0001
	this block holds class-level parameters, attached to ClassDesc More...
#define	P_AUTO_CONSTRUCT   0x0002
	instructs ClassDesc2 to autoconstuct this block & wire it in, requires pblock refno More...
#define	P_AUTO_UI   0x0004
	this block support automatic UI rollout managements, requires rollout template res ID, etc. More...
#define	P_USE_PARAMS   0x0008
	this block shares (exactly) the paramdefs from another descriptor, requires address of source descriptor More...
#define	P_INCLUDE_PARAMS   0x0010
	this block loads in a copy the paramdefs from another descriptor, requires address of source descriptor More...
#define	P_MULTIMAP   0x0020
	indicates this block as mulitple parameter maps ### move me More...
#define	P_CALLSETS_ON_LOAD   0x0040
	causes CallSets() to be called during load PLCB for this block More...
#define	P_HASCATEGORY   0x0080
	indicates, that category field is defined for rollup (after rollupproc) More...
#define	P_TEMPLATE_UI   0x0100
	indicates that dialog templates will be provided or constructed More...
#define	P_VERSION   0x0200
	Indicates a parameter block version number is specified. More...
#define	P_SCRIPTED_CLASS   0x1000
	belongs to a scripted plug-in class More...
#define	P_TEMPORARY   0x2000
	temporary descriptor built during scene load to support schema migration More...
#define	P_ANIMATABLE   0x00000001
	animatable param More...
#define	P_TRANSIENT   0x00000002
	do not store actual value, PBAccessor-derived More...
#define	P_NO_INIT   0x00000004
	do not initialize More...
#define	P_COMPUTED_NAME   0x00000008
	call compute name fn to get name More...
#define	P_INVISIBLE   0x00000010
	not visible in track view (if an animatable) More...
#define	P_RESET_DEFAULT   0x00000020
	do not make create params sticky, reset to defaults always More...
#define	P_SUBANIM   0x00000040
	non-animatable reference param is still a subanim (makes it visible in TV) More...
#define	P_TV_SHOW_ALL   0x00000080
	for Tab<> animatables, show all entries even if no controller assigned More...
#define	P_NO_REF   0x00000100
	for reftarg params do not maintain Reference automatically More...
#define	P_OWNERS_REF   0x00000200
	reference param maintained by owner, specify owner's reference number via the p_refno tag More...
#define	P_CAN_CONVERT   0x00000400
	indicates the p_classid validator is is in a CanConvertoTo() call, rather than as exact class More...
#define	P_SUBTEX   0x00000800
	indicates texmap param is kept by owner using MtlBase::xSubTexmap protocol, give subtex # in p_subtexno More...
#define	P_VARIABLE_SIZE   0x00001000
	Tab<> param is variable size allowing scripted changes. More...
#define	P_NO_AUTO_LABELS   0x00002000
	don't auto-set map & mtl names for associated button UI controls More...
#define	P_SHORT_LABELS   0x00004000
	use short auto names for associated button UI controls More...
#define	P_READ_ONLY   0x00008000
	this parameter is not assignable through MAXScript (allows try-and-buy 3rd-party plugins) More...
#define	P_OBSOLETE   0x40000000
	Indicates parameter is obsolete. More...
#define	P_READ_SECOND_FLAG_VALUE   0x80000000
	Indicates that a second per param constructor-specifiable flag value follows the first in the ParamBlockDesc2. More...
#define	P_USE_ACCESSOR_ONLY   0x00000001
	Indicates whether or not when doing a get or set on a param2 value that we only go through the accessor if one is available. More...
#define	P_IS_REF   0x0000000000010000
	is a reftarget param More...
#define	P_HAS_DEFAULT   0x0000000000020000
	has accessor function => a virtual param More...
#define	P_HAS_CUR_DEFAULT   0x0000000000040000
	has a snapshotted current default value More...
#define	P_HAS_MS_DEFAULT   0x0000000000080000
	has a MAXScript default More...
#define	P_HAS_RANGE   0x0000000000100000
	has a range specified More...
#define	P_HAS_CLASS_ID   0x0000000000200000
	a classID validator was given More...
#define	P_HAS_SCLASS_ID   0x0000000000400000
	an SClassID validator was given More...
#define	P_UI_ENABLED   0x0000000000800000
	indicates whether UI controls are initially enabled or diabled More...
#define	P_HAS_PROMPT   0x0000000001000000
	has status line prompt string res ID for various picker buttons More...
#define	P_HAS_CAPTION   0x0000000002000000
	has caption string res ID for open/save file dlgs More...
#define	P_HAS_FILETYPES   0x0000000004000000
	has file types string res ID for open/save file dlgs (in MAXScript type: form) More...
#define	P_HAS_REFNO   0x0000000008000000
	has refno supplied More...
#define	P_HAS_SUBTEXNO   0x0000000010000000
	has subtexno supplied More...
#define	P_INCLUDED   0x0000000020000000
	[INTERNAL ONLY] Sets a ParamDef as included from another descriptor. More...
#define	P_HAS_TOOLTIP   0x0001000000000000
	has ToolTip string More...
#define	P_HAS_ASSETTYPE   0x0002000000000000
	has asset type More...
#define	P_HAS_ASSETTYPENAME   0x0004000000000000
	has asset type name More...
#define	base_type(t)   ((ParamType2)((t) & ~(TYPE_TAB)))
	get base type ignoring Tab flag More...
#define	root_type(t)   ((ParamType2)((t) & ~(TYPE_TAB | TYPE_BY_VAL | TYPE_BY_REF | TYPE_BY_PTR)))
	get base type ignoring all flags More...
#define	is_tab(t)   ((t) & TYPE_TAB)
	is this param a table? More...
#define	is_by_val(t)   ((t) & TYPE_BY_VAL)
	is this param passed by value? (only for FnPub) More...
#define	is_by_ref(t)   ((t) & TYPE_BY_REF)
	is this param passed by reference? (only for FnPub) More...
#define	is_by_ptr(t)   ((t) & TYPE_BY_PTR)
	is this param passed by pointer? (only for FnPub) More...
#define	is_ref(d)   (((d).flags & (P_IS_REF | P_NO_REF | P_OWNERS_REF)) == P_IS_REF)
	is this param a true local refmaker? More...
#define	has_ui(d)   ((d).ctrl_count > 0)
	this param has UI info defined More...
#define	reftarg_type(t)
#define	IPARAMBLOCK2POSTLOADINFO_ID   Interface_ID(0x6c7b290a, 0x7c56423c)

Functions
PB2Export IParamBlock2 *	CreateParameterBlock2 (ParamBlockDesc2 *pdesc, ReferenceMaker *iowner)
PB2Export void	SetPB2MacroRecorderInterface (MacroRecorder *mri)
PB2Export IParamBlock2 *	UpdateParameterBlock2 (ParamBlockDescID *pdescOld, int oldCount, IParamBlock *oldPB, ParamBlockDesc2 *pdescNew, IParamBlock2 *newPB=NULL)
PB2Export int	CopyParamBlock2ToParamBlock (IParamBlock2 *pb2, IParamBlock *pb1, ParamBlockDescID *pdescPB1, int pb1Count)
PB2Export bool	IsParamTypeAnimatable (const ParamType2 t)

Macro Definition Documentation

#define P_CLASS_PARAMS   0x0001

this block holds class-level parameters, attached to ClassDesc

#define P_AUTO_CONSTRUCT   0x0002

instructs ClassDesc2 to autoconstuct this block & wire it in, requires pblock refno

#define P_AUTO_UI   0x0004

this block support automatic UI rollout managements, requires rollout template res ID, etc.

#define P_USE_PARAMS   0x0008

this block shares (exactly) the paramdefs from another descriptor, requires address of source descriptor

#define P_INCLUDE_PARAMS   0x0010

this block loads in a copy the paramdefs from another descriptor, requires address of source descriptor

#define P_MULTIMAP   0x0020

indicates this block as mulitple parameter maps ### move me

#define P_CALLSETS_ON_LOAD   0x0040

causes CallSets() to be called during load PLCB for this block

#define P_HASCATEGORY   0x0080

indicates, that category field is defined for rollup (after rollupproc)

#define P_TEMPLATE_UI   0x0100

indicates that dialog templates will be provided or constructed

#define P_VERSION   0x0200

Indicates a parameter block version number is specified.

When used as a ParamBlockDesc2 flag, a version number is expected immediately after the flags field, before the reference number field. This version number will be stored as ParamBlockDesc2::version and returned as IParamBlock2::GetVersion() indicates a version number is specified (integer value, before pblock refno)

#define P_SCRIPTED_CLASS   0x1000

belongs to a scripted plug-in class

#define P_TEMPORARY   0x2000

temporary descriptor built during scene load to support schema migration

#define P_ANIMATABLE   0x00000001

animatable param

#define P_TRANSIENT   0x00000002

do not store actual value, PBAccessor-derived

#define P_NO_INIT   0x00000004

do not initialize

#define P_COMPUTED_NAME   0x00000008

call compute name fn to get name

#define P_INVISIBLE   0x00000010

not visible in track view (if an animatable)

#define P_RESET_DEFAULT   0x00000020

do not make create params sticky, reset to defaults always

#define P_SUBANIM   0x00000040

non-animatable reference param is still a subanim (makes it visible in TV)

#define P_TV_SHOW_ALL   0x00000080

for Tab<> animatables, show all entries even if no controller assigned

#define P_NO_REF   0x00000100

for reftarg params do not maintain Reference automatically

#define P_OWNERS_REF   0x00000200

reference param maintained by owner, specify owner's reference number via the p_refno tag

#define P_CAN_CONVERT   0x00000400

indicates the p_classid validator is is in a CanConvertoTo() call, rather than as exact class

#define P_SUBTEX   0x00000800

indicates texmap param is kept by owner using MtlBase::xSubTexmap protocol, give subtex # in p_subtexno

#define P_VARIABLE_SIZE   0x00001000

Tab<> param is variable size allowing scripted changes.

#define P_NO_AUTO_LABELS   0x00002000

don't auto-set map & mtl names for associated button UI controls

#define P_SHORT_LABELS   0x00004000

use short auto names for associated button UI controls

#define P_READ_ONLY   0x00008000

this parameter is not assignable through MAXScript (allows try-and-buy 3rd-party plugins)

#define P_OBSOLETE   0x40000000

Indicates parameter is obsolete.

#define P_READ_SECOND_FLAG_VALUE   0x80000000

Indicates that a second per param constructor-specifiable flag value follows the first in the ParamBlockDesc2.

#define P_USE_ACCESSOR_ONLY   0x00000001

Indicates whether or not when doing a get or set on a param2 value that we only go through the accessor if one is available.

#define P_IS_REF   0x0000000000010000

is a reftarget param

#define P_HAS_DEFAULT   0x0000000000020000

has accessor function => a virtual param

#define P_HAS_CUR_DEFAULT   0x0000000000040000

has a snapshotted current default value

#define P_HAS_MS_DEFAULT   0x0000000000080000

has a MAXScript default

#define P_HAS_RANGE   0x0000000000100000

has a range specified

#define P_HAS_CLASS_ID   0x0000000000200000

a classID validator was given

#define P_HAS_SCLASS_ID   0x0000000000400000

an SClassID validator was given

#define P_UI_ENABLED   0x0000000000800000

indicates whether UI controls are initially enabled or diabled

#define P_HAS_PROMPT   0x0000000001000000

has status line prompt string res ID for various picker buttons

#define P_HAS_CAPTION   0x0000000002000000

has caption string res ID for open/save file dlgs

#define P_HAS_FILETYPES   0x0000000004000000

has file types string res ID for open/save file dlgs (in MAXScript type: form)

#define P_HAS_REFNO   0x0000000008000000

has refno supplied

#define P_HAS_SUBTEXNO   0x0000000010000000

has subtexno supplied

#define P_INCLUDED   0x0000000020000000

[INTERNAL ONLY] Sets a ParamDef as included from another descriptor.

If this is set on a ParamDef, its member ptrs have been copied from another descriptor, and will not be released

#define P_HAS_TOOLTIP   0x0001000000000000

has ToolTip string

#define P_HAS_ASSETTYPE   0x0002000000000000

has asset type

#define P_HAS_ASSETTYPENAME   0x0004000000000000

has asset type name

#define base_type

(

t

)

((ParamType2)((t) & ~(TYPE_TAB)))

get base type ignoring Tab flag

#define root_type

(

t

)

((ParamType2)((t) & ~(TYPE_TAB | TYPE_BY_VAL | TYPE_BY_REF | TYPE_BY_PTR)))

get base type ignoring all flags

#define is_tab

(

t

)

((t) & TYPE_TAB)

is this param a table?

#define is_by_val

(

t

)

((t) & TYPE_BY_VAL)

is this param passed by value? (only for FnPub)

#define is_by_ref

(

t

)

((t) & TYPE_BY_REF)

is this param passed by reference? (only for FnPub)

#define is_by_ptr

(

t

)

((t) & TYPE_BY_PTR)

is this param passed by pointer? (only for FnPub)

#define is_ref

(

d

)

(((d).flags & (P_IS_REF | P_NO_REF | P_OWNERS_REF)) == P_IS_REF)

is this param a true local refmaker?

#define has_ui

(

d

)

((d).ctrl_count > 0)

this param has UI info defined

#define reftarg_type

(

t

)

Value:

(base_type(t) == TYPE_MTL || base_type(t) == TYPE_TEXMAP || base_type(t) == TYPE_INODE || \
	                     base_type(t) == TYPE_REFTARG || base_type(t) == TYPE_PBLOCK2 || base_type(t) == TYPE_OBJECT || base_type(t) == TYPE_CONTROL)

#define IPARAMBLOCK2POSTLOADINFO_ID   Interface_ID(0x6c7b290a, 0x7c56423c)

Function Documentation

PB2Export IParamBlock2* CreateParameterBlock2	(	ParamBlockDesc2 *	pdesc,
		ReferenceMaker *	iowner
	)

Remarks

This method is used to create a parameter block2.

Parameters:

ParamBlockDesc2 *pdesc

This is an array of parameter block descriptors.

ReferenceMaker* iowner

Points to the owner of the parameter block.

Returns

A pointer to the created parameter block. On error NULL is returned.

PB2Export void SetPB2MacroRecorderInterface

(

MacroRecorder *

mri

)

Remarks

This function for internal use only.

PB2Export IParamBlock2* UpdateParameterBlock2	(	ParamBlockDescID *	pdescOld,
		int	oldCount,
		IParamBlock *	oldPB,
		ParamBlockDesc2 *	pdescNew,
		IParamBlock2 *	newPB = NULL
	)

Remarks

This function updates or creates a new ParamBlock2, based on an existing ParamBlock of an earlier version. The new parameter block inherits any parameters from the old parameter block whose parameter IDs match. This may also be used to partially update an existing ParamBlock2. The parameter type of the ParamBlock and ParamBlock2 entries must match, with a special case that if the ParamBlock parameter type is TYPE_RGBA, the ParamBlock2 parameter type can be either TYPE_RGBA or TYPE_FRGBA

Parameters:

ParamBlockDescID *pdescOld

The array of parameter block descriptors which describes each parameter in the old parameter block.

int oldCount

The number of elements in the array above.

IParamBlock *oldPB

The old parameter block.

ParamBlockDesc2* pdescNew

Points to the new parameter block 2 descriptor.

IParamBlock2* newPB=NULL

Points to an existing IParamBlock2 indicating that this paramblock should be filled in from the old ParamBlock, rather than creating a new one.

Returns

The new parameter block2.

PB2Export int CopyParamBlock2ToParamBlock	(	IParamBlock2 *	pb2,
		IParamBlock *	pb1,
		ParamBlockDescID *	pdescPB1,
		int	pb1Count
	)

Remarks

This function updates a ParamBlock based on an existing ParamBlock2. The ParamBlock inherits any parameters from the ParamBlock2 whose parameter IDs match. The parameter type of the ParamBlock and ParamBlock2 entries must match, with a special case that if the ParamBlock parameter type is TYPE_RGBA, the ParamBlock2 parameter type can be either TYPE_RGBA or TYPE_FRGBA This is mainly intended for use in Save To Previous, where the current version is ParamBlock2 based, and the old version is ParamBlock based. Note that if a ParamBlock2 parameter is animated, the ParamBlock2 will hold a reference to a controller for that parameter. This function does not clone the controller and have the ParamBlock hold a reference to that clone, rather the ParamBlock will hold a reference to the original controller. This is normally ok, since the ParamBlock will be deleted at the end of the save process. If the ParamBlock is being created other than for Save To Previous, you should consider replacing any references held by the ParamBlock with a clone of that reference.

Parameters:

IParamBlock2* pb2

Points to source IParamBlock2. IParamBlock* pb1

Points to destination IParamBlock. ParamBlockDescID *pdescPB1

The array of parameter block descriptors which describes each parameter in the ParamBlock.

int pb1Count

The number of elements in the array of parameter block descriptors.

Returns

The number of parameters copied from the IParamBlock2 to the IParamBlock.

bool Swirl::SpecifySaveReferences(ReferenceSaveManager& referenceSaveManager)
{
    // if saving to previous version that used pb1 instead of pb2...
    DWORD saveVersion = GetSavingVersion();
    if (saveVersion != 0 && saveVersion <= MAX_RELEASE_R13)
    {
        // create the pb1 instance
        IParamBlock* paramBlock1 = CreateParameterBlock( pbdesc,swirl_num_params_ver1,1);
        DbgAssert(paramBlock1 != NULL);
        if (paramBlock1)
        {
            // copy data from the pb2 to the pb1
            int numParamsCopied = CopyParamBlock2ToParamBlock(pblock,paramBlock1,pbdesc,swirl_num_params_ver1);
            DbgAssert(numParamsCopied == swirl_num_params_ver1);
            // register the reference slot replacement
            referenceSaveManager.ReplaceReferenceSlot(PBLOCK_REF,paramBlock1);
        }
    }
    return Texmap::SpecifySaveReferences(referenceSaveManager);
}

PB2Export bool IsParamTypeAnimatable

(

const ParamType2

t

)

Remarks

This function determines whether a param type is animatable.