Container to store blobs of arbitrary data for attributes. More...

#include <GA_BlobContainer.h>

Public Member Functions
	GA_BlobContainer ()

	~GA_BlobContainer ()

int64	getMemoryUsage (bool inclusive) const

void	countMemory (UT_MemoryCounter &counter, bool inclusive) const

int	capacity () const

int	entries () const

fpreal	getOccupancy () const

SYS_FORCE_INLINE GA_BlobRef	getBlob (GA_BlobIndex handle) const

SYS_FORCE_INLINE const GA_BlobData *	getRawBlob (GA_BlobIndex handle) const

GA_BlobIndex	replaceBlob (GA_BlobIndex prevhandle, const GA_BlobRef &blob)

exint	getIndexReferenceCount (GA_BlobIndex handle) const

bool	freeBlob (GA_BlobIndex handle)

void	clear ()

GA_BlobIndex	extractBlobs (UT_Array< GA_BlobRef > &array, UT_IntArray &handles) const

GA_BlobIndex	extractBlobs (UT_Array< GA_BlobRef > &array, UT_IntArray &handles, exint maxblobs) const

GA_BlobIndex	getMaximumIndex () const

bool	compactBlobs (UT_ValArray< GA_BlobIndex > &map)

void	replace (const GA_BlobContainer &src)
	Replaces the content of this with the content of src. More...


GA_BlobIndex	addBlob (const GA_BlobRef &blob)


void	addIndexReference (GA_BlobIndex handle, int inc)

void	addIndexReference (GA_BlobIndex handle)


bool	freeBlob (const GA_BlobRef &blob)

Detailed Description

Container to store blobs of arbitrary data for attributes.

The geometry library can store blobs of binary data for each object element. It does this by storing a shared reference count. Blobs are added to the blob container and accessed by integer handle (index).

As a developer, the semantics of:

handle = container.addBlob(blob);

are that the container will create a copy of the blob. It will associate an integer index with that blob and return the index.

To test whether a blob is in the container, you can call:

handle = container.getIndex(blob);

This will not add a blob to the container.

You get the blob back out of the container by calling:

blob = container.getBlob(handle);

It's important to realize that the blob you get back from the container is immutable. If you need to change the blob, you need to make a copy and store the modifed version in the container.

Blobs are deleted from the container by calling:

container.freeBlob(handle);

You should call freeBlob() for each blob you stored calling ()

Note: Blobs are stored using UT_COW. This enforces the fact that the blobs are immutable once they have been stored in the container. The container only provides read-pointers when you get blobs out of the container.

An example of how you might store a blob:

GA_BlobRef bref(new MyBlobSubClass());

handle = container.addBlob( bref );

Definition at line 71 of file GA_BlobContainer.h.

Constructor & Destructor Documentation

GA_BlobContainer::GA_BlobContainer ( )

GA_BlobContainer::~GA_BlobContainer ( )

Member Function Documentation

GA_BlobIndex GA_BlobContainer::addBlob ( const GA_BlobRef & blob )

Allocate a new blob and return the index to the blob.

Note: This method is thread safe

void GA_BlobContainer::addIndexReference	(	GA_BlobIndex	handle,
		int	inc
	)

inline

Add a reference to the blob given by the index. This is equivalent to:

addBlob( getBlob(handle) );

Note: This method is thread safe; inc must be positive.

Definition at line 195 of file GA_BlobContainer.h.

void GA_BlobContainer::addIndexReference ( GA_BlobIndex handle )

inline

Add a reference to the blob given by the index. This is equivalent to:

addBlob( getBlob(handle) );

Note: This method is thread safe; inc must be positive.

Definition at line 197 of file GA_BlobContainer.h.

int GA_BlobContainer::capacity ( ) const

inline

Allocated size of the container

Note: Not thread safe

Definition at line 93 of file GA_BlobContainer.h.

void GA_BlobContainer::clear ( )

inline

This will forcibly clear out all blobs, regardless of whether they have references. Use this with caution.

Note: Not thread safe

Definition at line 226 of file GA_BlobContainer.h.

bool GA_BlobContainer::compactBlobs ( UT_ValArray< GA_BlobIndex > & map )

Compact blobs can be called to "shrink" the index list (i.e. remove all vacancies in the index list). Since this will change the index values, a mapping array is returned which can be used to map the existing handle value to the new handle value. For example:

UT_ValArray<GA_BlobIndex> map;
GA_Range      range(...);
if (myBlobData.compactStrings(map)) {
    for (GA_Iterator it(range); !it.atEnd(); ++it)
        attribute_data[it.getOffset()] =
                         map(attribute_data[it.getOffset()]);
}

Note: Not thread safe

void GA_BlobContainer::countMemory	(	UT_MemoryCounter &	counter,
		bool	inclusive
	)		const

Count memory usage using a UT_MemoryCounter in order to count shared memory correctly. If inclusive is true, the size of this object is counted, else only memory owned by this object is counted. If this is pointed to by the calling object, inclusive should be true. If this is contained in the calling object, inclusive should be false. (Its memory was already counted in the size of the calling object.)

Note: Not thread safe

int GA_BlobContainer::entries ( ) const

inline

Occupied size of the container

Note: Not thread safe

Definition at line 97 of file GA_BlobContainer.h.

GA_BlobIndex GA_BlobContainer::extractBlobs	(	UT_Array< GA_BlobRef > &	array,
		UT_IntArray &	handles
	)		const

Extract the blobs into two arrays.

The array of blobs is the list of unique blobs in the container.
The handles are the corresponding integer handles The return code is the largest handle in the list (or -1 if there are no blobs in the container).
Warning
The maximum handle value may be is less than the number of blobs stored in the container. There may also be integer handles which aren't valid handles between 0 and the maximum.

Note
Not thread safe

GA_BlobIndex GA_BlobContainer::extractBlobs	(	UT_Array< GA_BlobRef > &	array,
		UT_IntArray &	handles,
		exint	maxblobs
	)		const

bool GA_BlobContainer::freeBlob ( GA_BlobIndex handle )

inline

Free the blob (de-reference) given by the handle

Note: This method is thread safe

Definition at line 210 of file GA_BlobContainer.h.

bool GA_BlobContainer::freeBlob ( const GA_BlobRef & blob )

inline

Free the given blob (de-reference) by blob pointer. This is equivalent to:

freeBlob( getIndex(blob) );

Note: This method is thread safe

Definition at line 219 of file GA_BlobContainer.h.

SYS_FORCE_INLINE GA_BlobRef GA_BlobContainer::getBlob ( GA_BlobIndex handle ) const

inline

Return the blob for a given handle. If the handle isn't valid, a NULL ptr will be returned.

Note: This method is thread safe

Definition at line 112 of file GA_BlobContainer.h.

exint GA_BlobContainer::getIndexReferenceCount ( GA_BlobIndex handle ) const

inline

For debugging purposes, this returns the number of references to this blob index in this map.

Definition at line 203 of file GA_BlobContainer.h.

GA_BlobIndex GA_BlobContainer::getMaximumIndex ( ) const

inline

Return the maximum index number used. If the maximum index is less than zero, there are no blobs in the container.

Warning: The maximum index value may be is greater than the number of blobs stored in the container. There may also be values which aren't bound to a blob between 0 and the maximum.

Note: Not thread safe

Definition at line 248 of file GA_BlobContainer.h.

int64 GA_BlobContainer::getMemoryUsage ( bool inclusive ) const

Report approximate memory usage (including storage for blobs)

Note: Not thread safe

fpreal GA_BlobContainer::getOccupancy ( ) const

inline

Get occupancy of the map which can be used to determine whether compaction is required.

Note: Not thread safe

Definition at line 103 of file GA_BlobContainer.h.

SYS_FORCE_INLINE const GA_BlobData* GA_BlobContainer::getRawBlob ( GA_BlobIndex handle ) const

inline

Return the blob for a given handle. If the handle isn't valid, a NULL ptr will be returned.

Note: This method is thread safe

Definition at line 122 of file GA_BlobContainer.h.

void GA_BlobContainer::replace ( const GA_BlobContainer & src )

Replaces the content of this with the content of src.

GA_BlobIndex GA_BlobContainer::replaceBlob	(	GA_BlobIndex	prevhandle,
		const GA_BlobRef &	blob
	)

inline

Return the n'th blob given in an ordered list of blobs. This method may be significantly more expensive than looking up by GA_BlobIndex or extracting all items at one time. For example:

      for (exint i = 0; ; ++i)
          {
          GA_BlobRef blob = blobcontainer.getOrderedBlob(i);
          if (!blob)
               break;
      }
    @note This method is @b not thread safe
GA_BlobRef              getOrderedBlob(exint index) const
                {
                    const MapItem       *item;
                    item = myMap.getOrderedItem(index);
                    return item ? item->getKey().getBlob()
                                : GA_BlobRef();
                }
    @{
    Look up an index for a given blob.  If the blob isn't in the container,
    the return code will be -1.
    @note This method is thread safe
GA_BlobIndex     getIndex(const GA_BlobRef &blob) const
                    { return myMap.findId(blob); }
    @}
    Blobs are stored in a sparse array.  When looping over all valid
    offsets, this method will "validate" the handle.  That is, if there's
    no blob stored at the location, it will map it to -1.
    @note This method is thread safe
GA_BlobIndex     validateIndex(GA_BlobIndex index) const;
    @{
    Replace the blob for the given index with a new blob.  The new index
    will be returned.  This is equivalent to: @code
                freeBlob(prevhandle);
                return addBlob(blob);

Note: This method is thread safe

Definition at line 167 of file GA_BlobContainer.h.

The documentation for this class was generated from the following file:

GA/GA_BlobContainer.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation