Class CyclicBuffer

Defined in File CyclicBufferApi.h

Class Documentation

class CyclicBuffer

This class contains cyclic buffer functions.

Public Functions

CyclicBuffer(WMX3Api *f): Constructor to initialize an object of this class. The device created by the WMX3Api object passed to this constructor is used to execute API functions. Also see Devices.

CyclicBuffer(const CyclicBuffer &src): Copy constructor to initialize an object of this class based on an existing object of this class. Also see Copy Operators.

CyclicBuffer &operator=(const CyclicBuffer &src): Copy assignment operator to initialize an object of this class based on an existing object of this class. Also see Copy Operators.

CyclicBuffer(): Constructor to initialize an object of this class with a self device. Also see Self Devices.

~CyclicBuffer(): Destructor for this class.

bool IsDeviceValid()

Return TRUE if this class object has access to a device, and FALSE otherwise. A device is required to execute most functions in this class. If this function returns FALSE, a device can be created by calling the CreateDevice function from the WMX3Api object that was passed to the constructor of this class.

WMX3APIFUNC GetVersion(int *pMajorVersion, int *pMinorVersion, int *pRevisionVersion, int *pFixVersion)

Get the version of the module rtdll.

Parameters:

pMajorVersion – [out] The major version number.
pMinorVersion – [out] The minor version number.
pRevisionVersion – [out] The revision version number.
pFixVersion – [out] The fix version number.

WMX3APIFUNC OpenCyclicBuffer(int axis, unsigned int numOfCycles)

Create a new cyclic buffer memory space for an axis.

The cyclic buffer memory space stores the queued cyclic commands.

Remark

One command is consumed each communication cycle while the cyclic buffer is running.

A larger cyclic buffer memory space can store more cyclic buffer commands in advance. Each cyclic command takes the size of CyclicBufferSingleAxisCommand to store.

The maximum size of the cyclic buffer memory space is 2GB-1Byte (2147483647 bytes). Specifying a larger size will cause this function to return the RequestedBufferTooLarge error.

Opened cyclic buffer memory spaces can be closed using CloseCyclicBuffer. Any cyclic buffer memory spaces that remain opened when the engine closes will be automatically closed.

Parameters:

axis – [in] The axis to create the cyclic buffer memory space for.
numOfCycles – [in] The number of cycles of data that can fit in the cyclic buffer memory space. Each cycle of data is represented by the CyclicBufferSingleAxisCommand class.

WMX3APIFUNC OpenCyclicBuffer(AxisSelection *pAxisSelection, unsigned int numOfCycles)

Create a new cyclic buffer memory space for multiple axes.

This function is an overload of OpenCyclicBuffer that opens the cyclic buffer memory space for multiple axes.

Remark

Parameters:

pAxisSelection – [in] A pointer to a AxisSelection that specifies which axes to create the cyclic buffer memory space for.
numOfCycles – [in] The number of cycles of data that can fit in the cyclic buffer memory space. Each cycle of data is represented by the CyclicBufferSingleAxisCommand class. This memory space is allocated to each axis specified by the pAxisSelection argument.

WMX3APIFUNC CloseCyclicBuffer(int axis)

Close the cyclic buffer memory space of an axis.

Cyclic buffer memory space that is opened with the OpenCyclicBuffer function can be closed with this function. Any cyclic buffer memory spaces that remain opened when the engine closes will be automatically closed.

Remark

Parameters:: axis – [in] The axis to close the cyclic buffer memory space of.

WMX3APIFUNC CloseCyclicBuffer(AxisSelection *pAxisSelection)

Close the cyclic buffer memory space of multiple axes.

This function is an overload of CloseCyclicBuffer that closes the cyclic buffer memory space for multiple axes.

Remark

Parameters:: pAxisSelection – [in] A pointer to a AxisSelection that specifies which axes to close the cyclic buffer memory space of.

WMX3APIFUNC AddCommand(int axis, CyclicBufferSingleAxisCommand *pCmd)

Add one position command data to the cyclic position command buffer of one axis.

If the cyclic position command buffer does not have enough space remaining to append a point, a BufferSizeIsNotEnough error is returned and no data is appended to the buffer.

Remark

Parameters:

axis – [in] The axis to append the cyclic position command data to.
pCmd – [in] A pointer to a CyclicBufferSingleAxisCommand class that contains the cyclic position command data.

WMX3APIFUNC AddCommand(int axis, CyclicBufferSingleAxisCommand *pCmd, int count)

Add any number of position command data to the cyclic position command buffer of one axis.

If the cyclic position command buffer does not have enough space remaining to append the specified number of points, a BufferSizeIsNotEnough error is returned and no data is appended to the buffer.

Remark

Parameters:

axis – [in] The axis to append the cyclic position command data to.
pCmd – [in] An array of objects of the CyclicBufferSingleAxisCommand class that contains the cyclic position command data. The number of objects in the array must equal the “count” argument.
count – [in] The number of objects in the pCmd array.

WMX3APIFUNC AddCommand(AxisSelection *pAxisSelection, CyclicBufferMultiAxisCommands *pCmds)

Add one position command data each to the cyclic position command buffer of multiple axes.

This function is a variation of the AddCommand function that appends one position command data each to multiple axes.

Remark

Parameters:

pAxisSelection – [in] A pointer to a AxisSelection that specifies which axes to append the cyclic position command data to.
pCmds – [in] A pointer to a CyclicBufferMultiAxisCommands class that contains the cyclic position command data of multiple axes.

WMX3APIFUNC AddCommand(AxisSelection *pAxisSelection, CyclicBufferMultiAxisCommands *pCmds, int count)

Add any number of position command data to the cyclic position command buffer of multiple axes.

This function is a variation of the AddCommand function that appends any number of position command data to multiple axes.

Remark

Parameters:

pAxisSelection – [in] A pointer to a AxisSelection that specifies which axes to append the cyclic position command data to.
pCmds – [in] An array of objects of the CyclicBufferMultiAxisCommands class that contains the cyclic position command data. The number of objects in the array must equal the “count” argument.
count – [in] The number of objects in the pCmds array.

WMX3APIFUNC Execute(int axis, CyclicBufferSingleAxisOption *pOption = NULL)

Start the execution of the cyclic position command buffer for a single axis.

An axis that is currently executing cyclic position commands will have an OperationState of DirectControl.

Remark

If the cyclic position command buffer is empty or becomes empty, execution will resume automatically the next time that cyclic position command data is appended to the buffer as long as the axis is still in DirectControl.

Parameters:

axis – [in] The axis to start execution of cyclic position commands.
pOption – [in] A pointer to a CyclicBufferSingleAxisOption class that contains execution options. If no value is specified for this optional argument, the default options will be applied.

WMX3APIFUNC Execute(AxisSelection *pAxisSelection, CyclicBufferMultiAxisOption *pOption = NULL)

Start the execution of the cyclic position command buffer for multiple axes.

This function is an overloaded function of Execute that starts the execution of the cyclic position command buffer for multiple axes.

Remark

Parameters:

pAxisSelection – [in] A pointer to a AxisSelection class that specifies the axes to start the execution of cyclic position commands.
pOption – [in] A pointer to a CyclicBufferMultiAxisOption class that contains execution options. If no value is specified for this optional argument, the default options will be applied.

WMX3APIFUNC Abort(int axis)

Stop execution of the cyclic position command buffer of an axis and clear the buffer.

An axis that stops executing cyclic position commands will return to the Idle state. The command velocity of the axis will suddenly become 0.

Remark

Any remaining position commands in the buffer will be cleared.

Parameters:: axis – [in] The axis to stop the execution of cyclic position commands.

WMX3APIFUNC Abort(AxisSelection *pAxisSelection)

Stop execution of the cyclic position command buffer of multiple axes and clear the buffer.

This function is an overloaded function of Abort that stops the execution of the cyclic position command buffer for multiple axes.

Remark

Parameters:: pAxisSelection – [in] A pointer to a AxisSelection class that specifies the axes to stop the execution of cyclic position commands.

WMX3APIFUNC ExecQuickStop(int axis)

Stop execution of the cyclic position command buffer of an axis and decelerate the axis to a stop using the quick stop deceleration.

The specified axis will stop executing the cyclic position command and decelerate from its current velocity using the Quick Stop Dec parameter. After the quick stop finishes, the axis will be in the Idle state.

Remark

Any remaining position commands in the buffer will be cleared.

Parameters:: axis – [in] The axis to stop the execution of cyclic position commands.

WMX3APIFUNC ExecQuickStop(AxisSelection *pAxisSelection)

Stop execution of the cyclic position command buffer of multiple axes and decelerate the axes to a stop using the quick stop deceleration.

This function is an overloaded function of ExecQuickStop that stops the execution of the cyclic position command buffer for multiple axes.

Remark

Parameters:: pAxisSelection – [in] A pointer to a AxisSelection class that specifies the axes to stop the execution of cyclic position commands.

WMX3APIFUNC GetStatus(int axis, CyclicBufferSingleAxisStatus *pStatus)

Get the cyclic position command buffer status of the specified axis.

This function retrieves the cyclic position command buffer status of one axis.

Remark

Parameters:

axis – [in] The axis to get the status of.
pStatus – [out] A pointer to a CyclicBufferSingleAxisStatus class which will return the cyclic position command buffer status of the specified axis.

WMX3APIFUNC GetStatus(AxisSelection *pAxisSelection, CyclicBufferMultiAxisStatus *pStatus)

Get the cyclic position command buffer status of the specified axes.

This function is an overloaded function of the GetStatus function that obtains the cyclic position command buffer status of multiple axes.

Remark

The axes to retrieve the statuses are specified using the pAxisSelection argument. The returned pStatus structure will contain the statuses in the same layout as the pAxisSelection argument, and not in the indices of the axis numbers. For example, if pAxisSelection.axisCount = 2, pAxisSelection.axis[0] = 10, and pAxisSelection.axis[1] = 20, then pStatus.status[0] will contain the status of axis 10 and pStatus.status[1] will contain the status of axis 20.

Parameters:

pAxisSelection – [in] A pointer to a AxisSelection class that specifies the axes to get the statuses of.
pStatus – [out] A pointer to a CyclicBufferMultiAxisStatus class which will return the cyclic position command buffer statuses of the specified axes.

Public Static Functions

static WMX3APIFUNC ErrorToString(int errCode, char *pString, unsigned int size)

Get a string representation of the specified error code.

This function returns a string representation of the specified error code. The error code must be defined in the CyclicBufferErrorCode enum or the ErrorCode enum in the WMX3Api.h header. All errors returned by functions in class CyclicBuffer will be defined in one of these enums. Errors returned by functions in other classes may not be defined in one of these enums, and when such errors are passed to this function, an ErrorCodeNotDefined error will be returned and pString will contain the string representation of this error.

Remark

If pString is too small to contain the entire string representation of the error code, pString will be set to an empty string. An array size of 256 characters will be enough to hold all string representations.

This function is static, and may be called without declaring an instance of the CyclicBuffer class or creating a device.

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A char array that will contain the string representation of the error.
size – [in] The size of the char array in number of characters.

static WMX3APIFUNC ErrorToString(int errCode, wchar_t *pString, unsigned int size)

Get a string representation of the specified error code.

This function is a variation of ErrorToString that accepts a wchar_t array. Use this function when using Unicode character sets.

Remark

Parameters:

errCode – [in] The error code to get the string representation of.
pString – [in] A wchar_t array that will contain the string representation of the error.
size – [in] The size of the wchar_t array in number of characters.

static WMX3APIFUNC ApiLogToString(unsigned char *pLogData, unsigned int logDataSize, char *pString, unsigned int size)

Get a string representation of the raw data of an API log.

This function converts the raw data for one API function call that was extracted from the API log with the GetApiLogData function.

Remark