HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
GA_BlobContainer Class Reference

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:

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()
}
@{
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: