Frame

Frame objects in C++ are referenced by the following shared pointer typedef:

typedef std::shared_ptr<rogue::interfaces::stream::Frame> rogue::interfaces::stream::FramePtr

Shared pointer alias for Frame.

The class description is shown below:

class Frame : public rogue::EnableSharedFromThis<rogue::interfaces::stream::Frame>

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).

Public Types

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

Iterator alias for the internal buffer list.

Public Functions

Frame()

Constructs an empty frame.

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

~Frame()

Destroys the frame instance.

std::shared_ptr<rogue::interfaces::stream::FrameLock> lock()

Locks the frame and returns a scoped lock object.

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.

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.

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.

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.

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.

std::vector<std::shared_ptr<rogue::interfaces::stream::Buffer>>::iterator beginBuffer()

Returns iterator to first underlying buffer.

Not exposed to Python.

This is for advanced manipulation of the underlying buffers.

Returns:

Iterator pointing to the start of the buffer list.

std::vector<std::shared_ptr<rogue::interfaces::stream::Buffer>>::iterator endBuffer()

Returns end iterator for underlying buffer list.

Not exposed to Python.

This is for advanced manipulation of the underlying buffers.

Returns:

Iterator pointing to the end of the buffer list.

uint32_t bufferCount()

Returns number of underlying buffers in the frame.

Not exposed to Python.

This is for advanced manipulation of the underlying buffers.

Returns:

Number of buffers in the list.

void clear()

Removes all buffers from the frame.

Not exposed to Python.

bool isEmpty()

Returns whether the frame contains no buffers.

Not exposed to Python.

Returns:

true if frame buffer list is empty.

uint32_t 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.

uint32_t 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.

uint32_t getPayload()

Returns current payload size in bytes.

Exposed as getPayload() in Python.

Returns:

Total payload bytes in the frame.

void setPayload(uint32_t size)

Sets payload size in bytes.

Not exposed to Python.

Parameters:

size – New payload size.

void 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.

void adjustPayload(int32_t value)

Adjusts payload size by a signed delta.

value is a positive or negative size adjustment.

Not exposed to Python.

Parameters:

value – Size adjustment value.

void setPayloadFull()

Sets payload size to full available frame capacity.

Sets payload size equal to total available buffer capacity.

Not exposed to Python.

void setPayloadEmpty()

Sets the frame payload size to zero bytes.

uint16_t getFlags()

Returns 16-bit frame flags field.

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.

void setFlags(uint16_t flags)

Sets 16-bit frame flags field.

Exposed as setFlags() in Python.

Parameters:

flags – 16-bit flag value.

uint8_t 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.

void 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.

uint8_t 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.

void 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.

uint8_t getChannel()

Returns frame channel value.

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.

void setChannel(uint8_t channel)

Sets frame channel value.

Exposed as setChannel() in Python.

Parameters:

channel – 8-bit channel ID.

uint8_t getError()

Returns frame error status value.

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.

void setError(uint8_t error)

Sets frame error status value.

Exposed as setError() in Python.

Parameters:

error – New error value.

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

Returns begin iterator over frame payload.

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.

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

Returns end iterator over frame payload.

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.

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

Returns legacy read-begin iterator.

Legacy alias retained for compatibility. Prefer begin().

Returns:

Iterator to payload start.

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

Returns legacy read-end iterator.

Legacy alias retained for compatibility. Prefer end().

Returns:

Iterator to payload end.

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

Returns legacy write-begin iterator.

Legacy alias retained for compatibility. Prefer begin().

Returns:

Iterator to payload start.

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

Returns legacy write-end iterator.

Legacy alias retained for compatibility. Prefer end().

Returns:

Iterator to payload end.

void readPy(boost::python::object p, uint32_t offset)

Reads frame bytes into a passed Python bytearray/buffer.

Exposed as read() to Python.

Parameters:

• p – Python object containing writable byte storage.

• offset – Byte offset in frame payload to start copying from.

boost::python::object getBytearrayPy(uint32_t offset, uint32_t count)

Reads frame bytes into a newly allocated Python bytearray.

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.

boost::python::object getMemoryviewPy()

Returns a Python memoryview of frame payload data.

Exposed as getMemoryview() to Python.

Returns:

Python memoryview object for frame payload.

void writePy(boost::python::object p, uint32_t offset)

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

Exposed as write() to Python.

Parameters:

• p – Python object containing source byte storage.

• offset – Byte offset in frame payload to start writing to.

boost::python::object getNumpy(uint32_t offset, uint32_t count)

Reads frame data and returns it as a NumPy uint8 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.

void putNumpy(boost::python::object np, uint32_t offset)

Writes NumPy array data into the frame payload.

Parameters:

• np – NumPy array containing source bytes.

• offset – Byte offset in frame payload to start writing to.

void debug()

Prints debug information for this frame.

Public Static Functions

static void setup_python()

Registers Python bindings for this class.

static std::shared_ptr<rogue::interfaces::stream::Frame> create()

Creates 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.