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

Initialize

Initializes the component

Add

Adds entry to palette

Find

Finds an entry in the palette

FindByResourcePtr

Pointer to finding an entry by resource

GetName

Returns the name associated with a given entry in the palette

GetPaletteSize

Returns the number of entries in the palette

DeleteByName

Deletes an entry in the palette

DeleteById

Deletes an entry in the palette

GetResourcePtr

Gets a pointer to the resource stored in a specific entry in the palette

GetResourcePtr

Gets a pointer to the resource stored in a specific entry in the palette and verifies that it's of a certain type

SetResourcePtr

Sets the resource pointer of a specific palette entry

CompactPalette

Compacts the palette and returns a handle to it

SetDefault

Sets the default entry in the palette

SetDefault

Sets the default entry in the palette

SetDefaultResourcePtr

Sets the default resource pointer

DeleteDefault

Deletes the default entry in the palette

First

Iterator method

Last

Iterator method

Next

Iterator method

Previous

Iterator method


IFXPalette:: Initialize(U32 uInitialSize, U32 uGrowthSize)

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

Return Values

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.


IFXPalette::Add(Char* | CIFXString* pPaletteEntryName, U32* pPaletteEntryId)

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

Return Values

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.


IFXPalette::Find(Char* | CIFXString* pPaletteEntryName, U32* pPaletteEntryId)

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

Return Values

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.


IFXPalette::FindByResourcePtr(IFXUnknown* pPointer, U32* pIndex)

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

Return Values


IFXPalette::GetName(U32 uPaletteEntryId, Char* | CIFXString* pPaletteEntryName)

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

Return Values


IFXPalette:: GetPaletteSize(U32* pPaletteSize)

Low level description of Initialize().

Parameters:

pPaletteSize

The number of active entries in the palette, NOT the physical size of the palette

Return Values

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.


IFXPalette:: DeleteByName(Char* | CIFXString* pPaletteEntryName)

This method deletes an entry in the palette with the specified name.

Parameters:

pPaletteEntryName

Name of the item to delete from the palette

Return Values

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.


IFXPalette:: DeleteById(U32 uPaletteEntryId)

This method deletes an entry from the palette.

Parameters:

uPaletteEntryId

Index of the entry to remove from the palette

Return Values

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.


IFXPalette:: GetResourcePtr(U32 uIndex, IFXUnknown** ppObject)

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)

Return Values

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.


IFXPalette:: GetResourcePtr(U32 uIndex, IFXREFIID interfaceId, void** ppObject)

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)

Return Values

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.


IFXPalette:: SetResourcePtr(U32 uIndex, IFXUnknown* pObject)

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

Return Values

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.


IFXPalette:: CompactPalette(U32** ppuMap)

This methods compacts the palette and returns a handle to the compacted form.

Parameters:

ppuMap

Handle to the compacted palette

Return Values


IFXPalette:: SetDefault(char* pPaletteEntryName, U32* pPaletteEntryId)

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

Return Values

Comments:

This method automatically deletes whatever was already in the default entry position - clearing its memory, and de-referencing its resources.


IFXPalette:: SetDefault(CIFXString* pPaletteEntryName)

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

Return Values

Comments:

This method automatically deletes whatever was already in the default entry position - clearing its memory, and de-referencing its resources.


IFXPalette::SetDefaultResourcePtr(IFXUnknown* pPointer)

This method sets the default palette entry by resource pointer.

Parameters:

pPointer

Pointer to IFXUnknown

Return Values


IFXPalette::DeleteDefault()

This method deletes the default settings.

Parameters:

None

Return Values


IFXPalette::First(U32* pID)

This method returns first palette entry.

Parameters:

pID

Pointer to the palette entry ID number

Return Values


IFXPalette::Last(U32* pID)

This method returns last palette entry.

Parameters:

pID

Pointer to the palette entry ID number

Return Values


IFXPalette::Next(U32* pID)

This method returns next palette entry.

Parameters:

pID

Pointer to the palette entry ID number

Return Values


IFXPalette::Previous(U32* pID)

This method returns previous palette entry.

Parameters:

pID

Pointer to the palette entry ID number

Return Values

§See asterisked (*) statement at Legal Information © 2001 Intel Corporation.