stk::Messager Class Reference

STK input control message parser. More...

#include <Messager.h>

Inheritance diagram for stk::Messager:

Public Member Functions
	Messager ()
	Default constructor.
	~Messager ()
	Class destructor.
void	popMessage (Skini::Message &message)
	Pop the next message from the queue and write it to the referenced message structure. More...
void	pushMessage (Skini::Message &message)
	Push the referenced message onto the message stack.
bool	setScoreFile (const char *filename)
	Specify a SKINI formatted scorefile from which messages should be read. More...
bool	startStdInput ()
	Initiate the "realtime" retreival from stdin of control messages into the queue. More...
bool	startSocketInput (int port=2001)
	Start a socket server, accept connections, and read "realtime" control messages into the message queue. More...
bool	startMidiInput (int port=0)
	Start MIDI input, with optional device and port identifiers. More...
void	ignoreSampleRateChange (bool ignore=true)
	A function to enable/disable the automatic updating of class data when the STK sample rate changes. More...

Static Public Member Functions
static StkFloat	sampleRate (void)
	Static method that returns the current STK sample rate.
static void	setSampleRate (StkFloat rate)
	Static method that sets the STK sample rate. More...
static void	clear_alertList ()
	Static method that frees memory from alertList_.
static std::string	rawwavePath (void)
	Static method that returns the current rawwave path.
static void	setRawwavePath (std::string path)
	Static method that sets the STK rawwave path.
static void	swap16 (unsigned char *ptr)
	Static method that byte-swaps a 16-bit data type.
static void	swap32 (unsigned char *ptr)
	Static method that byte-swaps a 32-bit data type.
static void	swap64 (unsigned char *ptr)
	Static method that byte-swaps a 64-bit data type.
static void	sleep (unsigned long milliseconds)
	Static cross-platform method to sleep for a number of milliseconds.
static bool	inRange (StkFloat value, StkFloat min, StkFloat max)
	Static method to check whether a value is within a specified range.
static void	handleError (const char *message, StkError::Type type)
	Static function for error reporting and handling using c-strings.
static void	handleError (std::string message, StkError::Type type)
	Static function for error reporting and handling using c++ strings.
static void	showWarnings (bool status)
	Toggle display of WARNING and STATUS messages.
static void	printErrors (bool status)
	Toggle display of error messages before throwing exceptions.

Static Public Attributes
static const StkFormat	STK_SINT8
static const StkFormat	STK_SINT16
static const StkFormat	STK_SINT24
static const StkFormat	STK_SINT32
static const StkFormat	STK_FLOAT32
static const StkFormat	STK_FLOAT64

Protected Member Functions
void	handleError (StkError::Type type) const
	Internal function for error reporting that assumes message in oStream_ variable.
virtual void	sampleRateChanged (StkFloat newRate, StkFloat oldRate)
	This function should be implemented in subclasses that depend on the sample rate.
void	addSampleRateAlert (Stk *ptr)
	Add class pointer to list for sample rate change notification.
void	removeSampleRateAlert (Stk *ptr)
	Remove class pointer from list for sample rate change notification.

Detailed Description

STK input control message parser.

This class reads and parses control messages from a variety of sources, such as a scorefile, MIDI port, socket connection, or stdin. MIDI messages are retrieved using the RtMidi class. All other input sources (scorefile, socket, or stdin) are assumed to provide SKINI formatted messages. This class can be compiled with generic, non-realtime support, in which case only scorefile reading is possible.

The various realtime message acquisition mechanisms (from MIDI, socket, or stdin) take place asynchronously, filling the message queue. A call to popMessage() will pop the next available control message from the queue and return it via the referenced Message structure. When a non-realtime scorefile is set, it is not possible to start reading realtime input messages (from MIDI, socket, or stdin). Likewise, it is not possible to read from a scorefile when a realtime input mechanism is running.

When MIDI input is started, input is also automatically read from stdin. This allows for program termination via the terminal window. An __SK_Exit_ message is pushed onto the stack whenever an "exit" or "Exit" message is received from stdin or when all socket connections close and no stdin thread is running.

This class is primarily for use in STK example programs but it is generic enough to work in many other contexts.

by Perry R. Cook and Gary P. Scavone, 1995–2019.

Member Function Documentation

popMessage()

void stk::Messager::popMessage

(

Skini::Message &

message

)

Pop the next message from the queue and write it to the referenced message structure.

Invalid messages (or an empty queue) are indicated by type values of zero, in which case all other message structure values are undefined. The user MUST verify the returned message type is valid before reading other message values.

setScoreFile()

bool stk::Messager::setScoreFile

(

const char *

filename

)

Specify a SKINI formatted scorefile from which messages should be read.

A return value of true indicates the call was successful. A return value of false can occur if the file is not found, cannot be opened, another file is currently still open, or if a realtime input mechanism is running. Scorefile input is considered to be a non-realtime control mechanism that cannot run concurrently with realtime input.

startStdInput()

bool stk::Messager::startStdInput

(

)

Initiate the "realtime" retreival from stdin of control messages into the queue.

This function initiates a thread for asynchronous retrieval of SKINI formatted messages from stdin. A return value of true indicates the call was successful. A return value of false can occur if a scorefile is being read, a stdin thread is already running, or a thread error occurs during startup. Stdin input is considered to be a realtime control mechanism that cannot run concurrently with non-realtime scorefile input.

startSocketInput()

bool stk::Messager::startSocketInput

(

int

port = 2001

)

Start a socket server, accept connections, and read "realtime" control messages into the message queue.

This function creates a socket server on the optional port (default = 2001) and starts a thread for asynchronous retrieval of SKINI formatted messages from socket connections. A return value of true indicates the call was successful. A return value of false can occur if a scorefile is being read, a socket thread is already running, or an error occurs during the socket server or thread initialization stages. Socket input is considered to be a realtime control mechanism that cannot run concurrently with non-realtime scorefile input.

startMidiInput()

bool stk::Messager::startMidiInput

(

int

port = 0

)

Start MIDI input, with optional device and port identifiers.

This function creates an RtMidiIn instance for MIDI input. The RtMidiIn class invokes a local callback function to read incoming messages into the queue. If port = -1, RtMidiIn will open a virtual port to which other software applications can connect (OS X and Linux only). A return value of true indicates the call was successful. A return value of false can occur if a scorefile is being read, MIDI input is already running, or an error occurs during RtMidiIn construction. Midi input is considered to be a realtime control mechanism that cannot run concurrently with non-realtime scorefile input.

setSampleRate()

static void stk::Stk::setSampleRate ( StkFloat  rate )

staticinherited

Static method that sets the STK sample rate.

The sample rate set using this method is queried by all STK classes that depend on its value. It is initialized to the default SRATE set in Stk.h. Many STK classes use the sample rate during instantiation. Therefore, if you wish to use a rate that is different from the default rate, it is imperative that it be set BEFORE STK objects are instantiated. A few classes that make use of the global STK sample rate are automatically notified when the rate changes so that internal class data can be appropriately updated. However, this has not been fully implemented. Specifically, classes that appropriately update their own data when either a setFrequency() or noteOn() function is called do not currently receive the automatic notification of rate change. If the user wants a specific class instance to ignore such notifications, perhaps in a multi-rate context, the function Stk::ignoreSampleRateChange() should be called.

ignoreSampleRateChange()

void stk::Stk::ignoreSampleRateChange ( bool  ignore = true )

inlineinherited

A function to enable/disable the automatic updating of class data when the STK sample rate changes.

This function allows the user to enable or disable class data updates in response to global sample rate changes on a class by class basis.

{ ignoreSampleRateChange_ = ignore; };

Member Data Documentation

STK_SINT8

const StkFormat stk::Stk::STK_SINT8

staticinherited

-128 to +127

STK_SINT16

const StkFormat stk::Stk::STK_SINT16

staticinherited

-32768 to +32767

STK_SINT24

const StkFormat stk::Stk::STK_SINT24

staticinherited

Lower 3 bytes of 32-bit signed integer.

STK_SINT32

const StkFormat stk::Stk::STK_SINT32

staticinherited

-2147483648 to +2147483647.

STK_FLOAT32

const StkFormat stk::Stk::STK_FLOAT32

staticinherited

Normalized between plus/minus 1.0.

STK_FLOAT64

const StkFormat stk::Stk::STK_FLOAT64

staticinherited

Normalized between plus/minus 1.0.

---

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

• Messager.h