Open Lighting Architecture: ola::DmxBuffer Class Reference

| Open Lighting Architecture 0.10.9

Loading...
Searching...
No Matches
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.
| DmxBuffer (const uint8_t *data, unsigned int length)
| Create a new buffer from raw data.
| DmxBuffer (const std::string &data)
| Create a new buffer from a string.
| ~DmxBuffer ()
| Destructor.
DmxBuffer & | operator= (const DmxBuffer &other)
| Assignment operator used to make this buffer equal to another buffer.
bool | operator== (const DmxBuffer &other) const
| Equality operator used to check if two DmxBuffers are equal.
bool | operator!= (const DmxBuffer &other) const
| Inequality operator used to check if two DmxBuffers are not equal.
unsigned int | Size () const
| Current size of DmxBuffer.
bool | HTPMerge (const DmxBuffer &other)
| HTP Merge from another DmxBuffer.
bool | Set (const uint8_t *data, unsigned int length)
| Set the contents of this DmxBuffer.
bool | Set (const std::string &data)
| Set the contents of this DmxBuffer equal to the string.
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.
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.
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.
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.
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.
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.
void | GetRange (unsigned int slot, uint8_t *data, unsigned int *length) const
| Get a range of values starting from a particular slot.
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.
const uint8_t * | GetRaw () const
| Get a raw pointer to the internal data.
std::string | Get () const
| Get the raw contents of the DmxBuffer as a string.
bool | Blackout ()
| Set the buffer to all zeros.
void | Reset ()
| Reset the buffer to hold no data.
std::string | ToString () const
| Convert the DmxBuffer to a human readable representation.

## 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

  other | The 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

  data | is a pointer to an array of data used to populate DmxBuffer
  length | is 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

  data | is 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]

string ola::DmxBuffer::Get | ( |  | ) | const

Get the raw contents of the DmxBuffer as a string.

Returns
  a string of raw channel values

## ◆ Get() [2/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

  data | is a pointer to an array to store the data from DmxBuffer
  length | is a pointer to the length of data

Postcondition
  *length == Size()

## ◆ Get() [3/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

  channel | is the channel to return

Returns
  the value for the requested channel, returns 0 if the channel does not exist

## ◆ 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

  | slot | is the dmx slot to start from
  | data | is a pointer to where you want to store the gathered data
  [in,out] | length | is 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

  other | the 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

  other | is 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

  other | the 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

  other | is 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 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

  other | is 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()

## ◆ Set() [2/3]

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

Set the contents of this DmxBuffer equal to the string.

Parameters

  data | the 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 uint8_t * | data,
|  | unsigned int | length )

Set the contents of this DmxBuffer.

Parameters

  data | is a pointer to an array of uint8_t values
  length | is the size of the array pointed to by data

Returns
  true if the set was successful, and false if it failed

Postcondition
  Size() == length

## ◆ 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

  channel | is the dmx channel you want to change
  data | is 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

  data | the 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

  offset | the starting channel
  data | a pointer to the new data
  length | the 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

  offset | the starting channel
  data | is the value to set the range to
  length | the 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:

- include/ola/DmxBuffer.h
- common/utils/DmxBuffer.cpp