DLLPlugin Class Reference

base class for all A:M plugins. More...

#include <DLLPlugi.h>

Inheritance diagram for DLLPlugin:

Inheritance graph
[legend]
Collaboration diagram for DLLPlugin:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 DLLPlugin ()
 DLLPlugin (HTreeObject *treeobject)
virtual ~DLLPlugin ()
void Init ()
virtual void Init (Time time)
virtual void Copy (const DLLPlugin &other)
HTreeObject * GetOwner ()
virtual UINT GetIconID ()
virtual UINT GetNameID ()
virtual char * GetClassName ()
virtual HProperty * GetPropertyAt (int i)
virtual int GetNumProperties ()
virtual BOOL Save (char *&label, char *&value, int count)
virtual BOOL ParseArg (const char *label, const char *value)
virtual BOOL OnNotifyEndProjectLoad (float productversion)
virtual HTreeObject ** GetPtrAt (int index)
void ReassignPtr (void *ptruplink, HTreeObject *newvalue)
virtual BOOL OnPtrMessage (PtrMessage ptrmessage, HTreeObject **ptruplink, LONG lparam, Time time=0)

Public Attributes

HINSTANCE m_hresource
HTreeObject * m_treeobject

Detailed Description

base class for all A:M plugins.

The functions are broken down into three main categories: Construction/Destruction, Interface and Serialization. A fourth category, Rendering, is defined in the derived classes.

Definition at line 21 of file DLLPlugi.h.

Constructor & Destructor Documentation

DLLPlugin::DLLPlugin (   )  [inline]
 

The constructor is where all the per-instance initialization is done for the texture. I say per-instance because within a given scene, a new copy of your plugin is created for every object it is applied to. This allows for time-based textures, for example, that are different on a per-instance basis.

There are however certain things that should not be instanced, but rather declared static within your derived class. Anything that is constant between all instances should be done this way to preserve memory, and sometimes initialization time. The most common case of this is a noise table in a texture derived class, which could be declared as a member variable somewhere in your class something like this.

static short noiz_tbl[MAXX][MAXY][MAXZ];

The constructor would then initialize it only if it hasn't already been done. Saving time and memory.

Definition at line 31 of file DLLPlugi.h.

References Init().

Here is the call graph for this function:

DLLPlugin::DLLPlugin (  HTreeObject *  htreeobject  )  [inline]
 

Parameters:
htreeobject - is a pointer to the plugins owner. It is the class that the plugin is member of. It is the actual class you see in the PWS tree. The constructor only uses it to set the member variable m_treeobject. This member is used for ReAssignPtr. This is also the pointer returned by GetOwner().
See also:
DLLPlugin::DLLPlugin()

Definition at line 32 of file DLLPlugi.h.

References Init(), and m_treeobject.

Here is the call graph for this function:

DLLPlugin::~DLLPlugin (   )  [inline, virtual]
 

Any allocations made by your plugin should be freed here.

Definition at line 33 of file DLLPlugi.h.

Member Function Documentation

void DLLPlugin::Copy (  const DLLPlugin &  other  )  [inline, virtual]
 

This function is called any time the plugin "cache" is changed. Its purpose is to give you the chance to copy any member variables to the instances of the plugin. An example might be the seamless flag on a projection map, here's what that code looks like.

void CustomTexture::Copy( const DLLPlugin &other )
{
  CustomTexture *cache = &(CustomTexture &)other;
  isseamless = cache->isseamless;
}

Definition at line 38 of file DLLPlugi.h.

char * DLLPlugin::GetClassName (   )  [inline, virtual]
 

Your company name and a plugin description (separated by a "\\") should be returned by this function (for example, return "Hash\\BBall". This string is used as a unique identifier to reload this plugin upon the Project being reloaded by Animation Master. Because the descriptive name received by loading the string resource for the ID returned by GetNameID() is localized, it cannot be used for comparison purposes. This string should not be localized, remaining the same no matter what language the machine may be using.

Definition at line 45 of file DLLPlugi.h.

Referenced by ImageIO::Write().

UINT DLLPlugin::GetIconID (   )  [inline, virtual]
 

The resource ID for your plugin's icon should be returned by this function. A 32x32 and a 16x16 version should be created for the icon. The larger of the two will be shown as a preview for your plugin in the available plugin attribute pannel. When your plugin is chosen, it's small icon becomes visible in the Project Workspace.

Definition at line 42 of file DLLPlugi.h.

UINT DLLPlugin::GetNameID (   )  [inline, virtual]
 

This should be the resource ID of a string resource for the name of your plugin. An ID is used rather than text to aid in localization.

Definition at line 44 of file DLLPlugi.h.

virtual int DLLPlugin::GetNumProperties (   )  [inline, virtual]
 

Definition at line 48 of file DLLPlugi.h.

References GetPropertyAt().

Here is the call graph for this function:

HTreeObject* DLLPlugin::GetOwner (   )  [inline]
 

Definition at line 39 of file DLLPlugi.h.

References m_treeobject.

HProperty * DLLPlugin::GetPropertyAt (  int  i  )  [inline, virtual]
 

In order for a property to show in plugin property panel of the PWS, the HProperty derived class must be assigned an index.

GetPropertyAt is continuously called until you return NULL. The count parameter 'i' starts out at zero on the first call, and increments for each subsequent call. For each property you wish to add to the property panel, you return the pointer to the apporpriate HProperty derived class instance. For example: 

HProperty *CustomTurbulence::GetPropertyAt( int i )
{
   switch (i) {
      case 0:
         return m_octaves;
      case 1:
         return m_density;
      case 2:
         return m_diameter;
      case 3:
         return m_euclid;
      default:
         return NULL;
   }
}

Parameters:
i - The index value corresponds to the position of the property UI in the panel.
Returns:
You must return A pointer to the HProperty derived class instance associated to the index position;
Note:
important Whenever a group of properties have been added into a HCategoryProperty, the HCategoryProperty variable needs to be returned by GetPropertyAt call but not the properties included in the category.

Definition at line 47 of file DLLPlugi.h.

Referenced by GetNumProperties().

virtual HTreeObject** DLLPlugin::GetPtrAt (  int  index  )  [inline, virtual]
 

Definition at line 61 of file DLLPlugi.h.

virtual void DLLPlugin::Init (  Time  time  )  [inline, virtual]
 

Definition at line 37 of file DLLPlugi.h.

void DLLPlugin::Init (   )  [inline]
 

Definition at line 66 of file DLLPlugi.h.

References m_hresource.

Referenced by DLLPlugin().

virtual BOOL DLLPlugin::OnNotifyEndProjectLoad (  float  productversion  )  [inline, virtual]
 

Definition at line 58 of file DLLPlugi.h.

References TRUE.

BOOL DLLPlugin::OnPtrMessage (  PtrMessage  ptrmessage,
HTreeObject **  ptruplink,
LONG  lparam,
Time  time = 0
)  [inline, virtual]
 

When a user clicks within the property control you will receive a call to your virtual OnPtrMessage function. 

BOOL CustomTexture::OnPtrMessage(PtrMessage ptrmessage, HTreeObject
**ptruplink, LONG lparam, Time time)
{
   int i=0;
   switch (ptrmessage )
   {
      case PTM_VALUESTORED: {
         HProperty *dueto = (HProperty*)lparam;
         if (dueto == m_buttonproperty) { // use your properties address here
                         ...
         }
         return TRUE;
      }
      case PTM_DELETED:
         m_mygroup = NULL;
         return TRUE;
      case PTM_RENAMED:
          // Group was renamed, might do something here
          return TRUE;
   return FALSE;
}

If anyone ever deletes the hgroup, the hgroup will notify all of its dependences (classes that called ReassignPtr with it as a parameter) that hgroup is being deleted. It does this through the OnPtrMessage virtual function in your DllPlugin class.

So lets say the user deletes the hgroup in the interface that your plugin has a pointer to. Your DLLPlugin class will receive an OnPtrMessage call that will notify you that the group was deleted.

Parameters:
ptrmessage - is set to one of the predefined in PtrMessage.
ptruplink -
lparam - Holds the HProperty object address (must be casted to the actual object type). If ptrmessage is of type PTM_FPSCHANGED then this parameter points to that new FPS value.
time -
Note:
PtrMessages are listed in file PtrMessa.h.

Definition at line 63 of file DLLPlugi.h.

References FALSE.

BOOL DLLPlugin::ParseArg (  const char *  label,
const char *  value
)  [inline, virtual]
 

Reading saved values back in is the job of ParseArg.

ParseArg is called for each line within the plugin parameters portion of a material file that the standard parser does not understand. This gives you the chance to handle the loading of this data. If you did parse the label, and decide it is one of yours, you should return TRUE, otherwise return FALSE. Here is an example of how to read what we wrote out in the previous example:

BOOL CustomTexture::ParseArg( const char *label, const char *value )
{
   if (strcmp(label, "ShowPreview") == 0) {
      showpreview = (strcmp(value, "ON") == 0);
      return TRUE;
   }
   return FALSE;
}

Note:
ParseArg is called when a v8.5 or earlier file is loaded or when a property not handled by the HProperty and HPropertyInfo derived classes.

Because the standard parser will stop calling this member function whenever it encounters a label that it recognize, the use of standard reserved parser words such as "Ambiance" for instance should be avoided. It is better to customize your labels by appending or prepending some letters such as your initials for example.

Definition at line 57 of file DLLPlugi.h.

References FALSE.

BOOL DLLPlugin::ReassignPtr (  void *  ptruplink,
HTreeObject *  newvalue
)  [inline]
 

ReassignPtr adds information to the assigned object that states that your class has a pointer to it. This information may be used later through calls to OnPtrMessage to let the plugin know that something have happened to the referenced object.

Lets say you have this member variable in your CustumTexture class:

HGroup *m_mygroup;

You can call

ReassignPtr(&m_mygroup,  hgroup);

This will set m_mygroup to hgroup. You do this rather than m_mygroup = group. What ReassignPtr actually does is adds information to the hgroup that states that your class has a pointer to it.

Note:
You do not have to explicitly assign your ptruplinks to NULL if you used DLLPlugin::GetPtrAt properly.
See also:
DLLPlugin::GetPtrAt (int index)
Parameters:
ptruplink - pointer to the local object pointer which holds the address of the referenced object.
newvalue - Pointer to the object which is assigned to ptruplink

Definition at line 62 of file DLLPlugi.h.

References m_treeobject, and HTreeObject::ReassignPtr().

Here is the call graph for this function:

BOOL DLLPlugin::Save (  char *&  label,
char *&  value,
int  count
)  [inline, virtual]
 

When a plugin specific parameter set is saved to disk, the Save function is called to write out your custom data. Some common examples of things written in this function are boolean variables, and filenames.

Save is continuously called until you return FALSE. The count variable starts out at zero on the first call, and increments for each subsequent call. For each item you wish to write you fill the label and value variables with the appropriate text. For example:

BOOL CustomTexture::Save( char *&label, char *&value, int count )
{
  switch (count) {
  case 0:
     label = "ShowPreview";
     value = showpreview ? "ON" : "OFF";
     return TRUE;
  }
  return FALSE;
}

This would write a line out in the material file that says "ShowPreview=ON". You would add more cases for each line you wish to write out.

Labels should be choosen so that they are not mistaken with any typical reserved labels in the A:M files. See CustomTexture::ParseArg for an explanation.

Note:
The Save function should be used for any data that are not properties derived from HProperty and associated with a derived class of HPropertyInfo. For HProperty associated to an HPropertyInfo. the values are automatically stored using the MatchName as tag.
See also:
HPropertyInfo

Definition at line 56 of file DLLPlugi.h.

References FALSE.

Member Data Documentation

HINSTANCE DLLPlugin::m_hresource
 

Definition at line 23 of file DLLPlugi.h.

Referenced by Init().

HTreeObject* DLLPlugin::m_treeobject
 

Definition at line 24 of file DLLPlugi.h.

Referenced by DLLPlugin(), GetOwner(), and ReassignPtr().

The documentation for this class was generated from the following files:
This A:M SDK v12.0 documentation is maintained by Hash Inc. Please address any comments concerning this documentation to AMReports. If you have any information, knowledge, or documentation to share with the A:M developer community, please post them on the Hash SDK forum.

Generated on Thu Oct 27 11:46:51 2005 with doxygen 1.4.5 written by Dimitri van Heesch, © 1997-2001