Container for one stream frame payload and metadata. More...

#include <Frame.h>

Inheritance diagram for rogue::interfaces::stream::Frame:

Public Types
typedef std::vector< std::shared_ptr< rogue::interfaces::stream::Buffer > >::iterator	BufferIterator
	Iterator alias for the internal buffer list.

Public Member Functions
	Frame ()
	Constructs an empty frame.

	~Frame ()
	Destroys the frame instance.

std::shared_ptr< rogue::interfaces::stream::FrameLock >	lock ()
	Locks the frame and returns a scoped lock object.

std::vector< std::shared_ptr< rogue::interfaces::stream::Buffer > >::iterator	appendFrame (std::shared_ptr< rogue::interfaces::stream::Frame > frame)
	Appends another frame's buffers to the end of this frame.

std::vector< std::shared_ptr< rogue::interfaces::stream::Buffer > >::iterator	appendBuffer (std::shared_ptr< rogue::interfaces::stream::Buffer > buff)
	Appends one buffer to the end of the frame.

std::vector< std::shared_ptr< rogue::interfaces::stream::Buffer > >::iterator	beginBuffer ()
	Returns iterator to first underlying buffer.

std::vector< std::shared_ptr< rogue::interfaces::stream::Buffer > >::iterator	endBuffer ()
	Returns end iterator for underlying buffer list.

uint32_t	bufferCount ()
	Returns number of underlying buffers in the frame.

void	clear ()
	Removes all buffers from the frame.

bool	isEmpty ()
	Returns whether the frame contains no buffers.

uint32_t	getSize ()
	Returns total raw frame capacity in bytes.

uint32_t	getAvailable ()
	Returns remaining available payload space in bytes.

uint32_t	getPayload ()
	Returns current payload size in bytes.

void	setPayload (uint32_t size)
	Sets payload size in bytes.

void	minPayload (uint32_t size)
	Expands payload size to at least the passed value.

void	adjustPayload (int32_t value)
	Adjusts payload size by a signed delta.

void	setPayloadFull ()
	Sets payload size to full available frame capacity.

void	setPayloadEmpty ()
	Sets the frame payload size to zero bytes.

uint16_t	getFlags ()
	Returns 16-bit frame flags field.

void	setFlags (uint16_t flags)
	Sets 16-bit frame flags field.

uint8_t	getFirstUser ()
	Returns the lower 8-bit user field from flags (SSI/Axi-Stream).

void	setFirstUser (uint8_t fuser)
	Sets the lower 8-bit user field in flags (SSI/Axi-Stream).

uint8_t	getLastUser ()
	Returns the upper 8-bit user field from flags (SSI/Axi-Stream).

void	setLastUser (uint8_t fuser)
	Sets the upper 8-bit user field in flags (SSI/Axi-Stream).

uint8_t	getChannel ()
	Returns frame channel value.

void	setChannel (uint8_t channel)
	Sets frame channel value.

uint8_t	getError ()
	Returns frame error status value.

void	setError (uint8_t error)
	Sets frame error status value.

rogue::interfaces::stream::FrameIterator	begin ()
	Returns begin iterator over frame payload.

rogue::interfaces::stream::FrameIterator	end ()
	Returns end iterator over frame payload.

rogue::interfaces::stream::FrameIterator	beginRead ()
	Returns legacy read-begin iterator.

rogue::interfaces::stream::FrameIterator	endRead ()
	Returns legacy read-end iterator.

rogue::interfaces::stream::FrameIterator	beginWrite ()
	Returns legacy write-begin iterator.

rogue::interfaces::stream::FrameIterator	endWrite ()
	Returns legacy write-end iterator.

void	readPy (boost::python::object p, uint32_t offset)
	Reads frame bytes into a passed Python bytearray/buffer.

boost::python::object	getBytearrayPy (uint32_t offset, uint32_t count)
	Reads frame bytes into a newly allocated Python bytearray.

boost::python::object	getMemoryviewPy ()
	Returns a Python `memoryview` of frame payload data.

void	writePy (boost::python::object p, uint32_t offset)
	Writes bytes from a Python bytearray/buffer into the frame.

boost::python::object	getNumpy (uint32_t offset, uint32_t count)
	Reads frame data and returns it as a NumPy `uint8` array.

void	putNumpy (boost::python::object np, uint32_t offset)
	Writes NumPy array data into the frame payload.

void	debug ()
	Prints debug information for this frame.

Public Member Functions inherited from rogue::EnableSharedFromThis< rogue::interfaces::stream::Frame >
std::shared_ptr< rogue::interfaces::stream::Frame >	shared_from_this ()
	Returns a `shared_ptr<T>` for this instance.

Public Member Functions inherited from rogue::EnableSharedFromThisBase
virtual	~EnableSharedFromThisBase ()
	Virtual destructor for polymorphic base usage.

Static Public Member Functions
static void	setup_python ()
	Registers Python bindings for this class.

static std::shared_ptr< rogue::interfaces::stream::Frame >	create ()
	Creates an empty frame.

Protected Member Functions
void	setSizeDirty ()
	Set size values dirty.

Protected Attributes
std::mutex	lock_

Friends
class	Buffer

class	FrameLock

Detailed Description

Container for one stream frame payload and metadata.

In Rogue stream interfaces, each logical frame in flight is represented by one Frame instance. The frame object does not directly allocate contiguous payload memory. Instead, it owns an ordered list of Buffer objects that provide the underlying storage.

FrameIterator traverses payload bytes across buffer boundaries, so higher-level protocol code can read or write frame content without manual buffer stitching. The frame also carries transport metadata (flags, channel, error) and payload accounting (size, payload, and available space).

Definition at line 56 of file Frame.h.

Member Typedef Documentation

◆ BufferIterator

typedef std::vector<std::shared_ptr<rogue::interfaces::stream::Buffer>>::iterator rogue::interfaces::stream::Frame::BufferIterator

Iterator alias for the internal buffer list.

Definition at line 93 of file Frame.h.

Constructor & Destructor Documentation

◆ Frame()

rogue::interfaces::stream::Frame::Frame ( )

Constructs an empty frame.

Create an empty frame.

This constructor is a low-level C++ allocation path. Prefer create() when shared ownership or Python exposure is required.

Definition at line 52 of file Frame.cpp.

◆ ~Frame()

rogue::interfaces::stream::Frame::~Frame ( )

Destroys the frame instance.

Destroy a frame.

Definition at line 62 of file Frame.cpp.

Member Function Documentation

◆ adjustPayload()

void rogue::interfaces::stream::Frame::adjustPayload ( int32_t value )

Adjusts payload size by a signed delta.

Adjust payload size.

value is a positive or negative size adjustment.

Not exposed to Python.

Parameters

value Size adjustment value.

Definition at line 224 of file Frame.cpp.

◆ appendBuffer()

rogue::interfaces::stream::Frame::BufferIterator rogue::interfaces::stream::Frame::appendBuffer ( std::shared_ptr< rogue::interfaces::stream::Buffer > buff )

Appends one buffer to the end of the frame.

Add a buffer to end of frame.

Not exposed to Python.

This is for advanced manipulation of the underlying buffers.

Parameters

buff	Buffer pointer (`BufferPtr`) to append.

Returns: Iterator pointing to the added buffer.

Definition at line 70 of file Frame.cpp.

◆ appendFrame()

rogue::interfaces::stream::Frame::BufferIterator rogue::interfaces::stream::Frame::appendFrame ( std::shared_ptr< rogue::interfaces::stream::Frame > frame )

Appends another frame's buffers to the end of this frame.

Append passed frame buffers to end of frame.

Buffers from the passed frame are appended to the end of this frame and will be removed from the source frame.

Not exposed to Python.

Parameters

frame Source frame pointer (FramePtr) to append.

Returns: Iterator pointing to the first inserted buffer from frame.

Definition at line 80 of file Frame.cpp.

◆ begin()

rogue::interfaces::stream::FrameIterator rogue::interfaces::stream::Frame::begin ( )

Returns begin iterator over frame payload.

Get start iterator.

Returns an iterator for accessing data within the frame. This iterator assumes the payload size of the frame has already been set. This means the frame has either been received already containing data, or the setPayload() method has been called.

Not exposed to Python.

Returns: FrameIterator pointing to beginning of payload.

Definition at line 322 of file Frame.cpp.

◆ beginBuffer()

rogue::interfaces::stream::Frame::BufferIterator rogue::interfaces::stream::Frame::beginBuffer ( )

Returns iterator to first underlying buffer.

Buffer begin iterator.

Not exposed to Python.

This is for advanced manipulation of the underlying buffers.

Returns: Iterator pointing to the start of the buffer list.

Definition at line 93 of file Frame.cpp.

◆ beginRead()

rogue::interfaces::stream::FrameIterator rogue::interfaces::stream::Frame::beginRead ( )

Returns legacy read-begin iterator.

Get write start iterator.

Legacy alias retained for compatibility. Prefer begin().

Returns: Iterator to payload start.

Definition at line 332 of file Frame.cpp.

◆ beginWrite()

rogue::interfaces::stream::FrameIterator rogue::interfaces::stream::Frame::beginWrite ( )

Returns legacy write-begin iterator.

Get read start iterator.

Legacy alias retained for compatibility. Prefer begin().

Returns: Iterator to payload start.

Definition at line 342 of file Frame.cpp.

◆ bufferCount()

uint32_t rogue::interfaces::stream::Frame::bufferCount ( )

Returns number of underlying buffers in the frame.

Buffer count.

Not exposed to Python.

This is for advanced manipulation of the underlying buffers.

Returns: Number of buffers in the list.

Definition at line 103 of file Frame.cpp.

◆ clear()

void rogue::interfaces::stream::Frame::clear ( )

Removes all buffers from the frame.

Clear the list.

Not exposed to Python.

Definition at line 108 of file Frame.cpp.

◆ create()

rogue::interfaces::stream::FramePtr rogue::interfaces::stream::Frame::create ( )

static

Creates an empty frame.

Create an empty frame.

This static factory is the preferred construction path when the object is shared across Rogue graph connections or exposed to Python. It returns std::shared_ptr ownership compatible with Rogue pointer typedefs. Not exposed to Python.

Returns: Shared pointer to the created frame.

Definition at line 46 of file Frame.cpp.

◆ debug()

void rogue::interfaces::stream::Frame::debug ( )

Prints debug information for this frame.

Definition at line 584 of file Frame.cpp.

◆ end()

rogue::interfaces::stream::FrameIterator rogue::interfaces::stream::Frame::end ( )

Returns end iterator over frame payload.

Get end iterator.

This iterator is used to detect when the end of the frame payload is reached when iterating through the frame.

Not exposed to Python.

Returns: FrameIterator end position.

Definition at line 327 of file Frame.cpp.

◆ endBuffer()

rogue::interfaces::stream::Frame::BufferIterator rogue::interfaces::stream::Frame::endBuffer ( )

Returns end iterator for underlying buffer list.

Buffer end iterator.

Not exposed to Python.

This is for advanced manipulation of the underlying buffers.

Returns: Iterator pointing to the end of the buffer list.

Definition at line 98 of file Frame.cpp.

◆ endRead()

rogue::interfaces::stream::FrameIterator rogue::interfaces::stream::Frame::endRead ( )

Returns legacy read-end iterator.

Get write end iterator.

Legacy alias retained for compatibility. Prefer end().

Returns: Iterator to payload end.

Definition at line 337 of file Frame.cpp.

◆ endWrite()

rogue::interfaces::stream::FrameIterator rogue::interfaces::stream::Frame::endWrite ( )

Returns legacy write-end iterator.

Get end of payload iterator.

Legacy alias retained for compatibility. Prefer end().

Returns: Iterator to payload end.

Definition at line 347 of file Frame.cpp.

◆ getAvailable()

uint32_t rogue::interfaces::stream::Frame::getAvailable ( )

Returns remaining available payload space in bytes.

This is the space remaining for payload.

Exposed as getAvailable() in Python.

Returns: Remaining bytes available for payload in the frame.

Definition at line 154 of file Frame.cpp.

◆ getBytearrayPy()

boost::python::object rogue::interfaces::stream::Frame::getBytearrayPy	(	uint32_t	offset,
		uint32_t	count
	)

Reads frame bytes into a newly allocated Python bytearray.

Allocate a bytearray and read bytes from frame into it starting at offset, return array.

Exposed as getBa() to Python.

Parameters

offset	Byte offset in frame payload to start reading from.
count	Number of bytes to read.

Returns: Python bytearray containing the copied bytes.

Definition at line 379 of file Frame.cpp.

◆ getChannel()

uint8_t rogue::interfaces::stream::Frame::getChannel ( )

Returns frame channel value.

Get channel.

Most Frames in Rogue will not use this channel field since most Master to Slave connections are not channelized. Exceptions include data coming out of a data file reader.

Exposed as getChannel() in Python.

Returns: 8-bit channel ID.

Definition at line 312 of file Frame.cpp.

◆ getError()

uint8_t rogue::interfaces::stream::Frame::getError ( )

Returns frame error status value.

Get error state.

The error value is application specific, depending on the stream Master implementation. A non-zero value is considered an error.

Exposed as getError() in Python.

Returns: Error status value.

Definition at line 302 of file Frame.cpp.

◆ getFirstUser()

uint8_t rogue::interfaces::stream::Frame::getFirstUser ( )

Returns the lower 8-bit user field from flags (SSI/Axi-Stream).

The first user value is stored in the lower 8 bits of the flag field.

Exposed as getFirstUser() in Python.

Returns: 8-bit first-user value.

Definition at line 279 of file Frame.cpp.

◆ getFlags()

uint16_t rogue::interfaces::stream::Frame::getFlags ( )

Returns 16-bit frame flags field.

Get flags.

The Frame flags field is a 16-bit application specific field for passing data between a stream Master and Slave. A typical use in Rogue is to pass the first and last user Axi-Stream fields.

Exposed as getFlags() in Python.

Returns: 16-bit flag value.

Definition at line 269 of file Frame.cpp.

◆ getLastUser()

uint8_t rogue::interfaces::stream::Frame::getLastUser ( )

Returns the upper 8-bit user field from flags (SSI/Axi-Stream).

The last user value is stored in the upper 8 bits of the flag field.

Exposed as getLastUser() in Python.

Returns: 8-bit last-user value.

Definition at line 290 of file Frame.cpp.

◆ getMemoryviewPy()

boost::python::object rogue::interfaces::stream::Frame::getMemoryviewPy ( )

Returns a Python memoryview of frame payload data.

Allocate a bytearray and from frame into it starting at offset, return memoryview to array.

Exposed as getMemoryview() to Python.

Returns: Python memoryview object for frame payload.

Definition at line 397 of file Frame.cpp.

◆ getNumpy()

boost::python::object rogue::interfaces::stream::Frame::getNumpy	(	uint32_t	offset,
		uint32_t	count
	)

Reads frame data and returns it as a NumPy uint8 array.

Read the specified number of bytes at the specified offset of frame data into a numpy array.

Parameters

offset	Byte offset in frame payload to start reading from.
count	Number of bytes to read.

Returns: One-dimensional NumPy array of uint8.

Definition at line 446 of file Frame.cpp.

◆ getPayload()

uint32_t rogue::interfaces::stream::Frame::getPayload ( )

Returns current payload size in bytes.

Exposed as getPayload() in Python.

Returns: Total payload bytes in the frame.

Definition at line 165 of file Frame.cpp.

◆ getSize()

uint32_t rogue::interfaces::stream::Frame::getSize ( )

Returns total raw frame capacity in bytes.

This function returns the full buffer size.

Exposed as getSize() in Python.

Returns: Total raw buffer size of frame in bytes.

Definition at line 144 of file Frame.cpp.

◆ isEmpty()

bool rogue::interfaces::stream::Frame::isEmpty ( )

Returns whether the frame contains no buffers.

Buffer list is empty.

Not exposed to Python.

Returns: true if frame buffer list is empty.

Definition at line 115 of file Frame.cpp.

◆ lock()

rogue::interfaces::stream::FrameLockPtr rogue::interfaces::stream::Frame::lock ( )

Locks the frame and returns a scoped lock object.

Get lock.

Acquire this lock before operating on a Frame object from user code, especially when reading or writing payload bytes, adjusting payload size, or changing metadata fields (flags, channel, error). This is the standard synchronization mechanism for frame access and should be treated as required whenever a frame can be observed or modified outside a single thread's private scope.

Exposed as lock() in Python.

Returns: Shared pointer to a FrameLock.

Definition at line 65 of file Frame.cpp.

◆ minPayload()

void rogue::interfaces::stream::Frame::minPayload ( uint32_t size )

Expands payload size to at least the passed value.

If current payload size is larger than the passed value, the payload size is unchanged.

Not exposed to Python.

Parameters

size	New minimum size.

Definition at line 219 of file Frame.cpp.

◆ putNumpy()

void rogue::interfaces::stream::Frame::putNumpy	(	boost::python::object	np,
		uint32_t	offset
	)

Writes NumPy array data into the frame payload.

Write the all the data associated with the input numpy array.

Parameters

np	NumPy array containing source bytes.
offset	Byte offset in frame payload to start writing to.

Definition at line 492 of file Frame.cpp.

◆ readPy()

void rogue::interfaces::stream::Frame::readPy	(	boost::python::object	p,
		uint32_t	offset
	)

Reads frame bytes into a passed Python bytearray/buffer.

Read bytes from frame into a passed bytearray, starting from offset. Python version.

Exposed as read() to Python.

Parameters

p	Python object containing writable byte storage.
offset	Byte offset in frame payload to start copying from.

Definition at line 354 of file Frame.cpp.

◆ setChannel()

void rogue::interfaces::stream::Frame::setChannel ( uint8_t channel )

Sets frame channel value.

Set channel.

Exposed as setChannel() in Python.

Parameters

channel 8-bit channel ID.

Definition at line 317 of file Frame.cpp.

◆ setError()

void rogue::interfaces::stream::Frame::setError ( uint8_t error )

Sets frame error status value.

Set error state.

Exposed as setError() in Python.

Parameters

error New error value.

Definition at line 307 of file Frame.cpp.

◆ setFirstUser()

void rogue::interfaces::stream::Frame::setFirstUser ( uint8_t fuser )

Sets the lower 8-bit user field in flags (SSI/Axi-Stream).

Exposed as setFirstUser() to Python.

Parameters

fuser 8-bit first-user value.

Definition at line 285 of file Frame.cpp.

◆ setFlags()

void rogue::interfaces::stream::Frame::setFlags ( uint16_t flags )

Sets 16-bit frame flags field.

Set error state.

Exposed as setFlags() in Python.

Parameters

flags 16-bit flag value.

Definition at line 274 of file Frame.cpp.

◆ setLastUser()

void rogue::interfaces::stream::Frame::setLastUser ( uint8_t fuser )

Sets the upper 8-bit user field in flags (SSI/Axi-Stream).

Exposed as setLastUser() to Python.

Parameters

fuser 8-bit last-user value.

Definition at line 296 of file Frame.cpp.

◆ setPayload()

void rogue::interfaces::stream::Frame::setPayload ( uint32_t size )

Sets payload size in bytes.

Not exposed to Python.

Parameters

size	New payload size.

Definition at line 175 of file Frame.cpp.

◆ setPayloadEmpty()

void rogue::interfaces::stream::Frame::setPayloadEmpty ( )

Sets the frame payload size to zero bytes.

Set the buffer as empty (minus header reservation)

Definition at line 253 of file Frame.cpp.

◆ setPayloadFull()

void rogue::interfaces::stream::Frame::setPayloadFull ( )

Sets payload size to full available frame capacity.

Set the buffer as full (minus tail reservation)

Sets payload size equal to total available buffer capacity.

Not exposed to Python.

Definition at line 237 of file Frame.cpp.

◆ setSizeDirty()

void rogue::interfaces::stream::Frame::setSizeDirty ( )

protected

Set size values dirty.

Definition at line 134 of file Frame.cpp.

◆ setup_python()

void rogue::interfaces::stream::Frame::setup_python ( )

static

Registers Python bindings for this class.

Definition at line 544 of file Frame.cpp.

◆ writePy()

void rogue::interfaces::stream::Frame::writePy	(	boost::python::object	p,
		uint32_t	offset
	)

Writes bytes from a Python bytearray/buffer into the frame.

Write python buffer to frame, starting at offset. Python Version.

Exposed as write() to Python.

Parameters

p	Python object containing source byte storage.
offset	Byte offset in frame payload to start writing to.

Definition at line 417 of file Frame.cpp.

Friends And Related Symbol Documentation

◆ Buffer

friend class Buffer

friend

Definition at line 57 of file Frame.h.

◆ FrameLock

friend class FrameLock

friend

Definition at line 58 of file Frame.h.

Member Data Documentation

◆ lock_

std::mutex rogue::interfaces::stream::Frame::lock_

protected

Definition at line 89 of file Frame.h.

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

/home/runner/work/rogue/rogue/include/rogue/interfaces/stream/Frame.h
/home/runner/work/rogue/rogue/src/rogue/interfaces/stream/Frame.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ BufferIterator

Constructor & Destructor Documentation

◆ Frame()

◆ ~Frame()

Member Function Documentation

◆ adjustPayload()

◆ appendBuffer()

◆ appendFrame()

◆ begin()

◆ beginBuffer()

◆ beginRead()

◆ beginWrite()

◆ bufferCount()

◆ clear()

◆ create()

◆ debug()

◆ end()

◆ endBuffer()

◆ endRead()

◆ endWrite()

◆ getAvailable()

◆ getBytearrayPy()

◆ getChannel()

◆ getError()

◆ getFirstUser()

◆ getFlags()

◆ getLastUser()

◆ getMemoryviewPy()

◆ getNumpy()

◆ getPayload()

◆ getSize()

◆ isEmpty()

◆ lock()

◆ minPayload()

◆ putNumpy()

◆ readPy()

◆ setChannel()

◆ setError()

◆ setFirstUser()

◆ setFlags()

◆ setLastUser()

◆ setPayload()

◆ setPayloadEmpty()

◆ setPayloadFull()

◆ setSizeDirty()

◆ setup_python()

◆ writePy()

Friends And Related Symbol Documentation

◆ Buffer

◆ FrameLock

Member Data Documentation

◆ lock_