IFXPalette |
The IFXPalette interface associates names with the resources used in Shockwave 3D§. It allows for more direct access using indexes instead of referring to entries by string names for performance. This structure creates a palette of Shockwave 3D objects to be selected and used. It automatically grows in size when needed using a binary growth pattern (doubling each time).
When to Use
A wide variety of Shockwave 3D components use the palette structure. It is at the heart of the data handling inside Shockwave 3D. All textures, models, materials, shaders, modifiers,and scheduler objects are stored in palettes. The scenegraph is responsible for keeping track of all the different kinds of palettes in the system. It is used any time you need a list of uniquely named resources stored in the system. The system is polymorphic, in that any object derived from IFXUnknown can be stored in it--you may even have a mix of different resource objects stored in one palette.
Here's a standard usage:
IFXPalette*
pPalette;
IFXSomeResource*
pResource;
U32 uIndex;
CreateComponent(IID_IFXPalette,
(void**) &pPalette);
pPalette->Initialize(10);
pPalette->Add("Box",
&uIndex);
pPalette->SetResourcePointer(uIndex,
pResource);
pPalette->Find("Box",
&uIndex);
pPalette->Release();
|
Interface Methods |
Description |
|
Initializes the component |
|
|
Adds entry to palette |
|
|
Finds an entry in the palette |
|
|
Pointer to finding an entry by resource |
|
|
Returns the name associated with a given entry in the palette |
|
|
Returns the number of entries in the palette |
|
|
Deletes an entry in the palette |
|
|
Deletes an entry in the palette |
|
|
Gets a pointer to the resource stored in a specific entry in the palette |
|
|
Gets a pointer to the resource stored in a specific entry in the palette and verifies that it's of a certain type |
|
|
Sets the resource pointer of a specific palette entry |
|
|
Compacts the palette and returns a handle to it |
|
|
Sets the default entry in the palette |
|
|
Sets the default entry in the palette |
|
|
Sets the default resource pointer |
|
|
Deletes the default entry in the palette |
|
|
Iterator method |
|
|
Iterator method |
|
|
Iterator method |
|
|
Iterator method |
This method initializes the palette's size and growth characteristics.
Parameters:
|
uInitialSize |
The initial number of entries to be allocated by the palette |
|
uGrowthSize |
When the palette is full, how much larger it should grow each time |
Comments:
The method must be called on a palette before any elements can be added to the palette. If growth size is not specified, its default behavior is to grow by doubling in size each time.
This method adds a new entry to the palette. Palette entries require unique names, so if you try to add a name that is already in the palette, you'll get the previously entered index.
Parameters:
|
pPaletteEntryName |
Name to add to the palette |
|
pPaletteEntryId |
ID number that is now associated with this name |
Comments:
This method is the workhorse of this component. It is responsible for adding a new entry to the palette. If the entry exists, it returns an error code and returns the ID of the previously existing entry. If the palette is full, it re-allocates the palette to make more room. It initializes the resource pointer to be null.
This method searches the palette for an entry with the specified name. It returns the ID number of that entry if found.
Parameters:
|
pPaletteEntryName |
Name of the entry you're looking for |
|
pPaletteEntryId |
ID of that entry if found |
Comments:
This method uses a separate data structure - the HashMap to do the actual string to ID lookups. The hashmap uses a hash table to improve lookup speed.
This method searches the palette for an entry by resource pointer. It returns the ID number of that entry if found.
Parameters:
|
pPointer |
Pointer to IFXUnknown |
|
pIndex |
Pointer to the index ID |
This method returns the name associated with a given palette entry index.
Parameters:
|
uPaletteEntryId |
Index of the item you'd like the name of |
|
pPaletteEntryName |
If found, the name of the entry at that index |
Low level description of Initialize().
Parameters:
|
pPaletteSize |
The number of active entries in the palette, NOT the physical size of the palette |
Comments:
This does not return how many free entries are in the palette, only the number of elements that actually have names associated with them.
This method deletes an entry in the palette with the specified name.
Parameters:
|
pPaletteEntryName |
Name of the item to delete from the palette |
Comments:
This method basically does a find to get the ID of the entry then calls the DeleteByID function. If the entry was pointing at a resource, that resource gets a Release() called on it to decrease its refcount.
This method deletes an entry from the palette.
Parameters:
|
uPaletteEntryId |
Index of the entry to remove from the palette |
Comments:
This method clears the palette entry. It does not decrease the physical size of the palette or modify the indexes of the other entries. It does deallocate the string name, removes it from the hashmap used for fast lookups and calls release on any resources pointed to by the entry.
This method returns the resource to which an entry in the palette is pointing. Because it's an IFXUnknown pointer, you will need to QueryInterface on the returned object to determine its exact type. The resource pointer may be NULL if it was never set using SetResourcePtr.
Parameters:
|
uIndex |
Index entry the resource pointer points to |
|
ppObject |
IFXUnknown pointer to the resource for that entry (if any) |
Comments:
This method returns a pointer to the resource as well as runs an AddRef(). You must call Release() on the returned pointer when you are finished. This method may return a null pointer.
This method returns the resource that a specific entry that's in the palette is pointing to. Unlike the other GetResourcePtr function, this method does the QueryInterface on the resource for you and returns a pointer to that exact type. The resource pointer may be NULL if that entry was never set using SetResourcePtr.
Parameters:
|
uIndex |
Index of the entry you want to set the resource pointer to |
|
interfaceId |
Interface ID of the object asked for |
|
ppObject |
Void pointer to the resource for that entry (if any) |
Comments:
This method returns a pointer to the resource as well as runs an AddRef(). You must call Release() on the returned pointer when you have finished. This method may return a null pointer. It is very similar to the other GetResourcePtr, except it runs the queryinterface() and returns a null pointer that is safe to cast into the interface you passed to.
Sets the resource pointer for a specific entry in the palette.
Parameters:
|
uIndex |
Index in the palette to set the resource pointer to |
|
pObject |
IFXUnknown pointer to the object associated with the named palette entry |
Comments:
This method should be called right after adding an entry to the palette. This method addref()'s the object you pass in and then sets a pointer to it internally for that entry. If the palette entry already had a resource associated with it, it does a Release() on the previous resource and then addref()'s and points to the new entry.
This methods compacts the palette and returns a handle to the compacted form.
Parameters:
|
ppuMap |
Handle to the compacted palette |
This method is used to set the default value in the palette. The default value has nothing to do with the actual palette implementation, but is used by components that reference the palette for default information.
Parameters:
|
pPaletteEntryName |
Name of the default entry to be added |
|
pPaletteEntryId |
ID number of the default entry to be added |
Comments:
This method automatically deletes whatever was already in the default entry position - clearing its memory, and de-referencing its resources.
This method is used to set the default value in the palette. The default value has nothing to do with the actual palette implementation, but is used by components that reference the palette for default information.
Parameters:
|
pPaletteEntryName |
Name of the default entry you wish to add |
Comments:
This method automatically deletes whatever was already in the default entry position - clearing its memory, and de-referencing its resources.
This method sets the default palette entry by resource pointer.
Parameters:
|
pPointer |
Pointer to IFXUnknown |
This method deletes the default settings.
Parameters:
None
This method returns first palette entry.
Parameters:
|
pID |
Pointer to the palette entry ID number |
This method returns last palette entry.
Parameters:
|
pID |
Pointer to the palette entry ID number |
This method returns next palette entry.
Parameters:
|
pID |
Pointer to the palette entry ID number |
This method returns previous palette entry.
Parameters:
|
pID |
Pointer to the palette entry ID number |
§See asterisked (*) statement at Legal Information © 2001 Intel Corporation.