PlayzerX API Reference

PlayzerX API Reference#

class PlayzerX#

Main interface to connect and control PlayzerX devices.

The PlayzerX class provides high-level methods to manage a device’s life cycle, exchange data, and query status. It supports both XYM and XYRGB data formats.

Public Functions

PlayzerX()#

Default constructor.

~PlayzerX()#

Destructor.

Cleans up the serial device if it has been created.

MTISerialIO *ConnectDevice()#

Opens the COM port and connects to the first detected device.

Note

This method uses the first available device from the discovery list.

Returns:

A pointer to an MTISerialIO instance if successful, otherwise nullptr.

MTISerialIO *ConnectDevice(const std::string &portName)#

Opens the COM port and connects to the device using a specified port name.

Parameters:

portName – The COM port name (e.g., “COM3”, “/dev/ttyUSB0”).

Returns:

A pointer to an MTISerialIO instance if successful, otherwise nullptr.

MTISerialIO *ConnectDevice(char *portName)#

Opens the COM port and connects to the device using a C-string port name.

Parameters:

portName – The COM port name in a C-string format (e.g., “COM3”).

Returns:

A pointer to an MTISerialIO instance if successful, otherwise nullptr.

bool IsDeviceConnected()#

Checks if a device is currently connected.

Returns:

true if the device is connected; otherwise false.

void DisconnectDevice()#

Stops communication and closes the COM port.

int GetSamplesRemaining()#

Retrieves the current number of remaining (unsent) samples.

Returns:

Number of samples left in the device buffer, or -1 on failure.

void SetBufferUpdateTimer(unsigned int bufferUpdateTimer)#

Sets the timer interval (in milliseconds) to update buffer levels.

Parameters:

bufferUpdateTimer – A value greater than zero enables periodic buffering updates.

void WaitForBufferLevel(int bufferLevelToSend = 25000)#

Blocks execution until the buffer level is below a specified threshold.

Parameters:

bufferLevelToSend – Desired buffer threshold, default is 25000.

void SendDataXYM(float x, float y, unsigned char m, int bufferLevelToSend = -1)#

Sends a single XYM sample (X, Y, modulation).

Parameters:

  • x – Normalized X coordinate in the range [-1.0, 1.0].

  • y – Normalized Y coordinate in the range [-1.0, 1.0].

  • m – Modulation value (e.g., intensity), range [0, 255].

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void SendDataXYM(float *x, float *y, unsigned char *m, unsigned int numSamples, int bufferLevelToSend = -1)#

Sends multiple XYM samples in array form.

Parameters:

  • x – Pointer to array of normalized X coordinates.

  • y – Pointer to array of normalized Y coordinates.

  • m – Pointer to array of modulation values.

  • numSamples – Number of samples to send.

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void SendDataXYM(std::vector<float> &x, std::vector<float> &y, std::vector<unsigned char> &m, int bufferLevelToSend = -1)#

Sends multiple XYM samples using std::vector containers.

Parameters:

  • x – Vector of normalized X coordinates.

  • y – Vector of normalized Y coordinates.

  • m – Vector of modulation values.

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void SendDataXY(float x, float y, int bufferLevelToSend = -1)#

Sends a single XY sample (no modulation).

Parameters:

  • x – Normalized X coordinate in the range [-1.0, 1.0].

  • y – Normalized Y coordinate in the range [-1.0, 1.0].

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void SendDataXY(float *x, float *y, unsigned int numSamples, int bufferLevelToSend = -1)#

Sends multiple XY samples in array form.

Parameters:

  • x – Pointer to array of normalized X coordinates.

  • y – Pointer to array of normalized Y coordinates.

  • numSamples – Number of samples to send.

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void SendDataXY(std::vector<float> &x, std::vector<float> &y, int bufferLevelToSend = -1)#

Sends multiple XY samples using std::vector containers.

Parameters:

  • x – Vector of normalized X coordinates.

  • y – Vector of normalized Y coordinates.

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void SendDataXYRGB(float x, float y, unsigned char r, unsigned char g, unsigned char b, int bufferLevelToSend = -1)#

Sends a single XYRGB sample.

Parameters:

  • x – Normalized X coordinate.

  • y – Normalized Y coordinate.

  • r – Red color component [0..255].

  • g – Green color component [0..255].

  • b – Blue color component [0..255].

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void SendDataXYRGB(float *x, float *y, unsigned char *r, unsigned char *g, unsigned char *b, unsigned int numSamples, int bufferLevelToSend = -1)#

Sends multiple XYRGB samples in array form.

Parameters:

  • x – Pointer to an array of normalized X coordinates.

  • y – Pointer to an array of normalized Y coordinates.

  • r – Pointer to an array of red color values [0..255].

  • g – Pointer to an array of green color values [0..255].

  • b – Pointer to an array of blue color values [0..255].

  • numSamples – Number of samples to send.

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void SendDataXYRGB(std::vector<float> &x, std::vector<float> &y, std::vector<unsigned char> &r, std::vector<unsigned char> &g, std::vector<unsigned char> &b, int bufferLevelToSend = -1)#

Sends multiple XYRGB samples using std::vector containers.

Parameters:

  • x – Vector of normalized X coordinates.

  • y – Vector of normalized Y coordinates.

  • r – Vector of red color values [0..255].

  • g – Vector of green color values [0..255].

  • b – Vector of blue color values [0..255].

  • bufferLevelToSend – Desired buffer threshold to wait for before sending.

void ClearData()#

Clears any queued data on the device and sends it to the origin.

void SetSampleRate(unsigned int sampleRate)#

Sets the sample rate for data output (e.g., 10,000 samples/sec).

Parameters:

sampleRate – The desired sample rate in samples per second (200..50000).

inline std::string GetDeviceName()#

Obtains the name of the connected device.

Returns:

String containing the device name.

inline std::string GetFirmwareName()#

Obtains the firmware version name of the connected device.

Returns:

String containing the firmware name.

inline std::string GetDataFormat()#

Obtains the data format (“XYM” or “XYRGB”).

Returns:

String indicating the current data format of the device.

inline std::string GetAPIVersion()#

Returns the version number of the PlayzerX API in x.y.z.w format.

Returns:

The version string, e.g., “2.0.1.0”.

inline PlayzerXError GetLastError()#

Gets the last error code generated by any operation on this device.

Returns:

A PlayzerXError enumeration value.

inline bool HasError()#

Checks if an error has been raised in the most recent operation.

Returns:

true if the last error was not SUCCESS; otherwise false.

void GetAvailableDevices(PlayzerXAvailableDevices &plad)#

Discovers all available PlayzerX devices connected to the system.

Parameters:

plad – A reference to PlayzerXAvailableDevices for storing the results.

void ListAvailableDevices(PlayzerXAvailableDevices &plad)#

Prints a summary of all discovered devices to the standard output.

Parameters:

plad – A PlayzerXAvailableDevices object containing the discovery results.

Public Static Functions

static PlayzerX *CreateDevice()#

Factory method to create a new PlayzerX device object.

static void DeleteDevice(PlayzerX *device)#

Safely deletes a PlayzerX device object created by CreateDevice().

class PlayzerXAvailableDevices#

Holds details for all discovered PlayzerX devices on the system.

Objects of this class store metadata for each detected device, including the device’s name, firmware name, data format, and COM port information.

Public Members

std::string DeviceName[MTI_MAXDEVICES]#

Read-only array of device names.

std::string FirmwareName[MTI_MAXDEVICES]#

Read-only array of firmware names.

std::string DataFormat[MTI_MAXDEVICES]#

Read-only array of data formats (e.g., “XYM” or “XYRGB”).

unsigned int USARTBaudRate[MTI_MAXDEVICES]#

Read-only array of UART baud rates for each device.

unsigned int CommPortNumber[MTI_MAXDEVICES]#

Read-only array of COM port numbers.

std::string CommPortName[MTI_MAXDEVICES]#

Read-only array of COM port names (e.g., “COM3”, “/dev/ttyUSB0”).

unsigned int NumDevices#

Number of devices detected.

enum class playzerx::PlayzerXError#

Enumerates possible error conditions within the PlayzerX library.

Values:

enumerator SUCCESS#

Operation completed successfully without error.

enumerator ERROR_GENERAL#

A generic error has occurred.

enumerator ERROR_CONNECTION#

Unable to establish or maintain a connection.

enumerator ERROR_INVALID_DEVICE_TYPE#

Invalid or unsupported device type was encountered.

enumerator ERROR_DISCONNECT#

Connection was closed or lost unexpectedly.

enumerator ERROR_PLAYZERX_RUNNING_STATE#

Device is in a running or busy state that prevents the operation.

enumerator ERROR_INVALID_PARAM#

One or more function parameters are invalid.

enumerator ERROR_FUNCTION_TIMEOUT#

Operation timed out while waiting for a response or condition.

enumerator ERROR_SCAN_NOT_SET#

The requested scan or data stream is not configured.