Geddei::BufferData Class Reference
[Geddei's core classes.]

Class for interfacing with signal data in Geddei. More...

#include <bufferdata.h>

Collaboration diagram for Geddei::BufferData:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 BufferData (const BufferData &source)
 BufferData (float *data, const uint size, const uint scope=1)
 BufferData (const float *data, const uint size, const uint scope=1)
 BufferData (const uint size, const uint scope=1)
 BufferData (const bool valid=false)
void copyFrom (const float *source)
void copyFrom (const BufferData &source)
void copyTo (float *destination) const
void debugInfo () const
const uint elements () const
void endWritePointer ()
const BufferID identity () const
const BufferInfo * info () const
BufferInfo * info ()
const bool isNull () const
const bool isValid () const
BufferData mid (const uint start, const uint length)
const BufferData mid (const uint start, const uint length) const
void nullify ()
float & operator() (const uint i, const uint j)
const float & operator() (const uint i, const uint j) const
BufferDataoperator= (const BufferData &source)
const float & operator[] (const uint i) const
float & operator[] (const uint i)
const bool plunger () const
const float * readPointer () const
BufferData sample (const uint index)
const BufferData sample (const uint index) const
BufferData samples (const uint index, const uint amount)
const BufferData samples (const uint index, const uint amount) const
const uint samples () const
const uint scope () const
float * writePointer ()
 ~BufferData ()

Static Public Member Functions

static BufferDatafake ()

Friends

class Buffer
class BufferReader
class DRCoupling
class LLConnection
class LRConnection
class LxConnection
ostream & operator<< (ostream &out, const BufferData &me)
class RLConnection
class RSCoupling
class Splitter

Detailed Description

Class for interfacing with signal data in Geddei.

Author:
Gav Wood <gav@cs.york.ac.uk>
BufferData objects are among the most important and well used objects in Geddei. The capture the essence of a data container. They present a simple and intuitive interface to the developer - that of a C-style array. They provide invisible data sharing capabilities. They provide methods to slice up data, to recreate data as C arrays, to introduce new data from C arrays, and to create new data chunks either with a new databank (i.e. not shared) or sharing data from a given array.

Elements (individual values) of data may be accessed either by their position or in a tabular manner by accessing an element of a sample.

There are such things as null BufferData objects which may or may not be valid. Validity and nullness may be ascertained by the isValid() and isNull() methods. A null BufferData object stores no data. If it is still valid, undert most cases you need not care that it is null, since it is essentially masquerading as a real data storage object. If invalid, then it must not be written to or accessed in any other way since it represents (essentially) a null and discarded pointer.

Note:
This class is not explicitly thread-safe; you should only access a BufferData object or any derivatives (made my copying it, using mid(), samples() and sample()) by one thread at once.


Constructor & Destructor Documentation

Geddei::BufferData::BufferData ( const bool  valid = false  ) 

Creates a null bufferdata object.

Parameters:
valid If false (default), any attempt to access it will result in an error. Otherwise, it will still be useable, but wont actually store anything.

Geddei::BufferData::BufferData ( const uint  size,
const uint  scope = 1 
)

Creates a bufferdata object whose data is self-managed.

Allocates size floats for its use that are deallocated when last reference dies. Allows use of readPointer() for easy integration with other systems.

Parameters:
size The size of this BufferData object in elements.
scope The number of elements contained in each sample. This must be a divisor of size.

Geddei::BufferData::BufferData ( const float *  data,
const uint  size,
const uint  scope = 1 
)

Creates a read-only BufferData object whose data is foreign.

Allows use of readPointer() for easy integration with other systems.

Parameters:
data The databank which this BufferData will adopt. As you never want this array to be written to, declare the BufferData object const.
size The size of this BufferData object in elements. This must not be larger than the size of the data given in data or memory corruption will occur.
scope The number of elements contained in each sample. This must be a divisor of size.

Geddei::BufferData::BufferData ( float *  data,
const uint  size,
const uint  scope = 1 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Creates a writable BufferData object whose data is foreign.

Allows use of readPointer() for easy integration with other systems.

Parameters:
data The databank which this BufferData will adopt.
size The size of this BufferData object in elements. This must not be larger than the size of the data given in data or memory corruption will occur.
scope The number of elements contained in each sample. This must be a divisor of size.

Geddei::BufferData::BufferData ( const BufferData source  ) 

Copy constructor. Acts like the assignment operator in that it adopts the same databank as the given BufferDatat source.

Data changed in one may affect the other.

Parameters:
source The BufferData object from which to adopt the data.

Geddei::BufferData::~BufferData (  ) 

Intelligent destructor.


Member Function Documentation

void Geddei::BufferData::copyFrom ( const float *  source  ) 

Copies contents of src into this object's data store.

Parameters:
source *must* be the same size as this, i.e. elements() floats long. If not you'll get memory corruption.

void Geddei::BufferData::copyFrom ( const BufferData source  ) 

Copies contents of a given BufferData to this object's data store.

Can be useful when you need to output into a BufferData object different from one that you must put the output into (when in a SubProcessor).

You generally shouldn't need to use this in a normal Processor object.

Parameters:
source The BufferData object from which to copy the data. The two BufferData objects sizes must be the same (in elements).

void Geddei::BufferData::copyTo ( float *  destination  )  const

Copies all this data into a float array given by destination.

Parameters:
destination *must* be the same size as this, i.e. elements() floats long. If not you'll get memory corruption.

const uint Geddei::BufferData::elements (  )  const [inline]

Used to get the number of elements (single values) used to represent this data.

You will generally not want to work in elements, but instead samples. Be very sure you know what you are doing before you use element-related methods.

Returns:
The number of elements in the data.

void Geddei::BufferData::endWritePointer (  )  [inline]

Forces propogation of the previously borrowed array into this BufferData object. You should call this before you attempt to push() the data.

This pointer is invalid after this call.

const bool Geddei::BufferData::isNull (  )  const [inline]

Tests for nullness - a null BufferData object can be used (if valid), but access will be meaningless.

Returns:
true iff this BufferData is null.

const bool Geddei::BufferData::isValid (  )  const [inline]

Tests for validity (invalid means it should never be used).

Returns:
true iff the BufferData object is valid.

BufferData Geddei::BufferData::mid ( const uint  start,
const uint  length 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Get another BufferData object referencing some portion of elements in this one.

You will generally not want to work in elements, but instead samples. Be very sure you know what you are doing before you use element-related methods.

Note:
The returned object is merely an illusionary object; the new object will, if pushed into a buffer, still push the same data as this one would. The scope of the transformation is only use this in so far as reading from or writing to the this object. It has no effect on other external actions or objects.
Parameters:
start The element on which the portion will begin.
length The length of the portion to refer to in elements.
Returns:
A new (shared data) BufferData object that points to a section from this object's data.

const BufferData Geddei::BufferData::mid ( const uint  start,
const uint  length 
) const

Get another BufferData object referencing some portion of elements in this one.

You will generally not want to work in elements, but instead samples. Be very sure you know what you are doing before you use element-related methods.

Note:
The returned object is merely an illusionary object; the new object will, if pushed into a buffer, still push the same data as this one would. The scope of the transformation is only use this in so far as reading from or writing to the this object. It has no effect on other external actions or objects.
Parameters:
start The element on which the portion will begin.
length The length of the portion to refer to in elements.
Returns:
A new (shared data) BufferData object that points to the section from this object's data.

void Geddei::BufferData::nullify (  )  [inline]

Makes this bufferdata invalid, ending the life of the previous data.

If this is the last reference to the data, any death-effects of the data will be carried out as they would be if the last reference object was deleted.

float& Geddei::BufferData::operator() ( const uint  i,
const uint  j 
) [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Operator to give easy and transparent access to the data contained within. The parentheses operator will return a specific element of a given sample is a table-esque lookup.

Note:
If compiled with -DEDEBUG, they do access, bounds and validity checking.
Parameters:
i The sample to be accessed.
j The element of sample i to be accessed. This must be less than the size (scope) of a sample.
Returns:
The value of the element at position j in sample i .

const float& Geddei::BufferData::operator() ( const uint  i,
const uint  j 
) const [inline]

Operator to give easy and transparent access to the data contained within. The parentheses operator will return a specific element of a given sample is a table-esque lookup.

Note:
If compiled with -DEDEBUG, they do access, bounds and validity checking.
Parameters:
i The sample to be accessed.
j The element of sample i to be accessed. This must be less than the size (scope) of a sample.
Returns:
The value of the element at position j in sample i .

BufferData & Geddei::BufferData::operator= ( const BufferData source  ) 

Assignment operator. This is used to set this BufferData object to become equivalent to the BufferData object source.

This doesn't actually copy the data - it merely makes another reference to the data that source uses. Changing data in one may alter the other's content.

We release our reference to the data contained in this and any resources it used may be freed.

Note:
To duplicate the data (i.e. copy the data in source over our current data, use copyFrom() instead.
Parameters:
source The BufferData object from which we will gather our data's reference.
Returns:
A reference to this object.

const float& Geddei::BufferData::operator[] ( const uint  i  )  const [inline]

Array subscript type Operator to give easy and transparent access to the data contained within. This access the data in a raw manner giving direct access to the elements.

You will generally *not* want to use this, instead using the parentheses operator.

Note:
If compiled with -DEDEBUG, they do access, bounds and validity checking.
Parameters:
i The element to be accessed.
Returns:
The value of the element at position i .

float& Geddei::BufferData::operator[] ( const uint  i  )  [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Array subscript type Operator to give easy and transparent access to the data contained within. This access the data in a raw manner giving direct access to the elements.

You will generally *not* want to use this, instead using the parentheses operator.

Note:
If compiled with -DEDEBUG, they do access, bounds and validity checking.
Parameters:
i The element to be accessed.
Returns:
The value of the element at position i .

const bool Geddei::BufferData::plunger (  )  const

Used for checking if this data chunk was terminated by a plunger. Plungers cause premature readElements() calls.

Returns:
true iff this data is terminated by a plunger.

const float* Geddei::BufferData::readPointer (  )  const [inline]

Gives a single array of floats, the same length as the number of elements in this BufferData.

As it's a const method, we assume that the array will be used for reading the data from. You are therefore guaranteed that it will contain the same data as would be read from this BufferData object.

This should only be used if you *really* need an array (e.g. for interfacing to external libraries). Use the []/() operators for normal usage.

Note:
Using this method may invalidate any explicit data sharing of the buffer. If this was based on sharing a databank with another BufferData (such as through samples() or the assignment operator), they may now no longer share the same databank.
Returns:
An array representation of the datastore of this object, or zero if the BufferData is null (isNull() returns true). You should either check before using readPointer() with isNull(), or check the return value of readPointer(). If zero, there is no need to populate the BufferData since the data will not be used.

BufferData Geddei::BufferData::sample ( const uint  index  ) 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Get another BufferData object referencing a sample of data in this one.

Note:
The returned object is merely an illusionary object; the new object will, if pushed into a buffer, still push the same data as this one would. The scope of the transformation is only use this in so far as reading from or writing to the this object. It has no effect on other external actions or objects.
Parameters:
index The sample to be refered to.
Returns:
A new (shared data) BufferData object that points to the specific sample from this object's data.

const BufferData Geddei::BufferData::sample ( const uint  index  )  const

Get another BufferData object referencing a sample of data in this one.

Note:
The returned object is merely an illusionary object; the new object will, if pushed into a buffer, still push the same data as this one would. The scope of the transformation is only use this in so far as reading from or writing to the this object. It has no effect on other external actions or objects.
Parameters:
index The sample to be refered to.
Returns:
A new (shared data) BufferData object that points to the specific sample from this object's data.

BufferData Geddei::BufferData::samples ( const uint  index,
const uint  amount 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns a new (shared data) BufferData object that points to specific samples from this object's data.

Note:
The returned object is merely an illusionary object; the new object will, if pushed into a buffer, still push the same data as this one would. The scope of the transformation is only use this in so far as reading from or writing to the this object. It has no effect on other external actions or objects.
Parameters:
index The sample from which the range of data to be refered to begins.
amount The number of samples to be refered to.
Returns:
A new (shared data) BufferData object that points to the specific samples from this object's data.

const BufferData Geddei::BufferData::samples ( const uint  index,
const uint  amount 
) const

Returns a new (shared data) BufferData object that points to specific samples from this object's data.

Note:
The returned object is merely an illusionary object; the new object will, if pushed into a buffer, still push the same data as this one would. The scope of the transformation is only use this in so far as reading from or writing to the this object. It has no effect on other external actions or objects.
Parameters:
index The sample from which the range of data to be refered to begins.
amount The number of samples to be refered to.
Returns:
A new (shared data) BufferData object that points to the specific samples from this object's data.

const uint Geddei::BufferData::samples (  )  const [inline]

Used to get the number of elements inside the data chunk.

Returns:
The number of samples in the data.

float* Geddei::BufferData::writePointer (  )  [inline]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Gives a single array of floats, the same length as the number of elements in this BufferData. Writing to the array is tantamount to writing to the BufferData object.

This should only be used if you *really* need an array (e.g. for interfacing to external libraries). Use the []/() operators for normal usage.

As it's not a const method, we assume that BufferData doesn't contain data yet, so array wont contain anything.

The pointer returned will only be valid as long as this object exists. As soon as this object goes out of scope, the pointer will become invalid. This means that the following code is incorrect:

 BufferData &d(someBufferData);
 float *f = d.sample(0).writePointer();
 f[0] = 0;
 d.sample(0).endWritePointer()

This is because by the time we come to write to the array, the BufferData object used to make the borrowArray() call (given by d.sample(0)) will have been destroyed through being anonymous and therefore out of scope. The endWritePointer() call will be useless since it is being called on a different instance.

You must instead deanonymise it with a named BufferData instance:

 BufferData &d(someBufferData);
 BufferData portion = d.sample(0);
 float *f = portion.writePointer();
 someExternalFunctionThatPopulates(f);
 portion.endWritePointer();

Note:
You must call endWritePointer() when finished with this array, and the data in the array is not guaranteed to propogate to the data in this object until you do.
Returns:
An array representation of the datastore of this object, or zero if the BufferData is null (isNull() returns true). You should either check before using readPointer() with isNull(), or check the return value of readPointer(). If zero, there is no need to populate the BufferData since the data will not be used.


The documentation for this class was generated from the following files:
Generated on Fri Nov 10 21:58:31 2006 for Exscalibar by  doxygen 1.5.1