Open Lighting Architecture  Latest Git
Public Member Functions | List of all members
ola::DmxBuffer Class Reference

Detailed Description

Used to hold a single universe of DMX data.

DmxBuffer is used to hold a single universe of DMX data. This class includes functions to translate to/from strings, and manipulate channels in the buffer.

Note
DmxBuffer uses a copy-on-write (COW) optimization, more info can be found here: http://en.wikipedia.org/wiki/Copy-on-write
This class is NOT thread safe.

Public Member Functions

 DmxBuffer ()
 
 DmxBuffer (const DmxBuffer &other)
 Copy constructor. We just copy the underlying pointers and mark m_copy_on_write as true if the other buffer has data. More...
 
 DmxBuffer (const uint8_t *data, unsigned int length)
 Create a new buffer from raw data. More...
 
 DmxBuffer (const std::string &data)
 Create a new buffer from a string. More...
 
 ~DmxBuffer ()
 Destructor.
 
DmxBufferoperator= (const DmxBuffer &other)
 Assignment operator used to make this buffer equal to another buffer. More...
 
bool operator== (const DmxBuffer &other) const
 Equality operator used to check if two DmxBuffers are equal. More...
 
bool operator!= (const DmxBuffer &other) const
 Inequality operator used to check if two DmxBuffers are not equal. More...
 
unsigned int Size () const
 Current size of DmxBuffer. More...
 
bool HTPMerge (const DmxBuffer &other)
 HTP Merge from another DmxBuffer. More...
 
bool Set (const uint8_t *data, unsigned int length)
 Set the contents of this DmxBuffer. More...
 
bool Set (const std::string &data)
 Set the contents of this DmxBuffer equal to the string. More...
 
bool Set (const DmxBuffer &other)
 Sets the data in this buffer to be the same as the other one. This forces a copy of the data rather than using copy-on-write. More...
 
bool SetFromString (const std::string &data)
 Set values from a string. Convert a comma separated list of values into for the DmxBuffer. Invalid values are set to 0. 0s can be dropped between the commas. More...
 
bool SetRangeToValue (unsigned int offset, uint8_t data, unsigned int length)
 Set a Range of data to a single value. Calling this on an uninitialized buffer will call Blackout() first. Attempted to set data with an offset greater than Size() is an error. More...
 
bool SetRange (unsigned int offset, const uint8_t *data, unsigned int length)
 Set a range of data. Calling this on an uninitialized buffer will call Blackout() first. Attempting to set data with an offset > Size() is an error. More...
 
void SetChannel (unsigned int channel, uint8_t data)
 Set a single channel. Calling this on an uninitialized buffer will call Blackout() first. Trying to set a channel more than 1 channel past the end of the valid data is an error. More...
 
void Get (uint8_t *data, unsigned int *length) const
 Get the contents of this DmxBuffer. This function copies the contents of the DmxBuffer into the memory region pointed to by data. More...
 
void GetRange (unsigned int slot, uint8_t *data, unsigned int *length) const
 Get a range of values starting from a particular slot. More...
 
uint8_t Get (unsigned int channel) const
 This function returns the value of a channel, and returns 0 if the buffer wasn't initialized or the channel was out-of-bounds. More...
 
const uint8_t * GetRaw () const
 Get a raw pointer to the internal data. More...
 
std::string Get () const
 Get the raw contents of the DmxBuffer as a string. More...
 
bool Blackout ()
 Set the buffer to all zeros. More...
 
void Reset ()
 Reset the buffer to hold no data. More...
 
std::string ToString () const
 Convert the DmxBuffer to a human readable representation. More...
 

Constructor & Destructor Documentation

◆ DmxBuffer() [1/4]

ola::DmxBuffer::DmxBuffer ( )

Constructor This initializes an empty DmxBuffer, Size() == 0

◆ DmxBuffer() [2/4]

ola::DmxBuffer::DmxBuffer ( const DmxBuffer other)

Copy constructor. We just copy the underlying pointers and mark m_copy_on_write as true if the other buffer has data.

Parameters
otherThe other DmxBuffer to copy from

◆ DmxBuffer() [3/4]

ola::DmxBuffer::DmxBuffer ( const uint8_t *  data,
unsigned int  length 
)

Create a new buffer from raw data.

Parameters
datais a pointer to an array of data used to populate DmxBuffer
lengthis the length of data in array data

◆ DmxBuffer() [4/4]

ola::DmxBuffer::DmxBuffer ( const std::string &  data)
explicit

Create a new buffer from a string.

Parameters
datais a string of raw data values
Deprecated:
Use DmxBuffer(const uint8_t *data, unsigned int length) instead

Member Function Documentation

◆ Blackout()

bool ola::DmxBuffer::Blackout ( )

Set the buffer to all zeros.

Postcondition
Size() == DMX_UNIVERSE_SIZE

◆ Get() [1/3]

void ola::DmxBuffer::Get ( uint8_t *  data,
unsigned int *  length 
) const

Get the contents of this DmxBuffer. This function copies the contents of the DmxBuffer into the memory region pointed to by data.

Parameters
datais a pointer to an array to store the data from DmxBuffer
lengthis a pointer to the length of data
Postcondition
*length == Size()

◆ Get() [2/3]

uint8_t ola::DmxBuffer::Get ( unsigned int  channel) const

This function returns the value of a channel, and returns 0 if the buffer wasn't initialized or the channel was out-of-bounds.

Parameters
channelis the channel to return
Returns
the value for the requested channel, returns 0 if the channel does not exist

◆ Get() [3/3]

string ola::DmxBuffer::Get ( ) const

Get the raw contents of the DmxBuffer as a string.

Returns
a string of raw channel values

◆ GetRange()

void ola::DmxBuffer::GetRange ( unsigned int  slot,
uint8_t *  data,
unsigned int *  length 
) const

Get a range of values starting from a particular slot.

Parameters
slotis the dmx slot to start from
datais a pointer to where you want to store the gathered data
[in,out]lengthis the length of the data you wish to retrieve

◆ GetRaw()

const uint8_t* ola::DmxBuffer::GetRaw ( ) const
inline

Get a raw pointer to the internal data.

Returns
constant pointer to internal data

◆ HTPMerge()

bool ola::DmxBuffer::HTPMerge ( const DmxBuffer other)

HTP Merge from another DmxBuffer.

Parameters
otherthe DmxBuffer to HTP merge into this one
Returns
false if the merge failed, and true if merge was successful

◆ operator!=()

bool ola::DmxBuffer::operator!= ( const DmxBuffer other) const

Inequality operator used to check if two DmxBuffers are not equal.

Parameters
otheris the other DmxBuffer to check against
Returns
true if not equal and false if the are equal

◆ operator=()

DmxBuffer & ola::DmxBuffer::operator= ( const DmxBuffer other)

Assignment operator used to make this buffer equal to another buffer.

Parameters
otherthe other DmxBuffer to copy/link from

◆ operator==()

bool ola::DmxBuffer::operator== ( const DmxBuffer other) const

Equality operator used to check if two DmxBuffers are equal.

Parameters
otheris the other DmxBuffer to check against
Returns
true if equal, and false if not

◆ Reset()

void ola::DmxBuffer::Reset ( )

Reset the buffer to hold no data.

Postcondition
Size() == 0

◆ Set() [1/3]

bool ola::DmxBuffer::Set ( const uint8_t *  data,
unsigned int  length 
)

Set the contents of this DmxBuffer.

Parameters
datais a pointer to an array of uint8_t values
lengthis the size of the array pointed to by data
Returns
true if the set was successful, and false if it failed
Postcondition
Size() == length

◆ Set() [2/3]

bool ola::DmxBuffer::Set ( const std::string &  data)

Set the contents of this DmxBuffer equal to the string.

Parameters
datathe string with the dmx data
Returns
true if the set was successful and false if it failed
Postcondition
Size() == data.length()

◆ Set() [3/3]

bool ola::DmxBuffer::Set ( const DmxBuffer other)

Sets the data in this buffer to be the same as the other one. This forces a copy of the data rather than using copy-on-write.

Parameters
otheris another DmxBuffer with data to point to/copy from
Returns
true if the set was successful and false if it failed
Postcondition
Size() == other.Size()

◆ SetChannel()

void ola::DmxBuffer::SetChannel ( unsigned int  channel,
uint8_t  data 
)

Set a single channel. Calling this on an uninitialized buffer will call Blackout() first. Trying to set a channel more than 1 channel past the end of the valid data is an error.

Parameters
channelis the dmx channel you want to change
datais the value to set channel

◆ SetFromString()

bool ola::DmxBuffer::SetFromString ( const std::string &  data)

Set values from a string. Convert a comma separated list of values into for the DmxBuffer. Invalid values are set to 0. 0s can be dropped between the commas.

Parameters
datathe string to split
Returns
true if the set was successful and false if it failed
Example
Here is an example of the string format used:
dmx_buffer.SetFromString("0,1,2,3,4")
The above code would set channels 1 through 5 to 0,1,2,3,4 respectively, and
dmx_buffer.SetFromString(",,,,,255,255,128")
would set channel 1 through 5 to 0 and channel 6,7 to 255 and channel 8 to 128.

◆ SetRange()

bool ola::DmxBuffer::SetRange ( unsigned int  offset,
const uint8_t *  data,
unsigned int  length 
)

Set a range of data. Calling this on an uninitialized buffer will call Blackout() first. Attempting to set data with an offset > Size() is an error.

Parameters
offsetthe starting channel
dataa pointer to the new data
lengththe length of the data
Returns
true if the call successful and false if it failed

◆ SetRangeToValue()

bool ola::DmxBuffer::SetRangeToValue ( unsigned int  offset,
uint8_t  data,
unsigned int  length 
)

Set a Range of data to a single value. Calling this on an uninitialized buffer will call Blackout() first. Attempted to set data with an offset greater than Size() is an error.

Parameters
offsetthe starting channel
datais the value to set the range to
lengththe length of the range to set
Returns
true if the call successful and false if it failed

◆ Size()

unsigned int ola::DmxBuffer::Size ( ) const
inline

Current size of DmxBuffer.

Returns
the current number of slots in the buffer.

◆ ToString()

string ola::DmxBuffer::ToString ( ) const

Convert the DmxBuffer to a human readable representation.

Returns
a string in a human readable form
Example
Here is an example of the output.
"0,0,255,128,100"

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