292 lines
11 KiB
C++
292 lines
11 KiB
C++
|
/**
|
||
|
|
* Copyright (c) 2014-2018 Enzien Audio Ltd.
|
||
|
|
*
|
||
|
|
* Permission to use, copy, modify, and/or distribute this software for any
|
||
|
|
* purpose with or without fee is hereby granted, provided that the above
|
||
|
|
* copyright notice and this permission notice appear in all copies.
|
||
|
|
*
|
||
|
|
* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
|
||
|
|
* REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
|
||
|
|
* AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||
|
|
* INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
|
||
|
|
* LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
|
||
|
|
* OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
|
||
|
|
* PERFORMANCE OF THIS SOFTWARE.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef _HEAVY_CONTEXT_INTERFACE_H_
|
||
|
|
#define _HEAVY_CONTEXT_INTERFACE_H_
|
||
|
|
|
||
|
|
#include "HvUtils.h"
|
||
|
|
|
||
|
|
#ifndef _HEAVY_DECLARATIONS_
|
||
|
|
#define _HEAVY_DECLARATIONS_
|
||
|
|
|
||
|
|
class HeavyContextInterface;
|
||
|
|
struct HvMessage;
|
||
|
|
|
||
|
|
typedef enum {
|
||
|
|
HV_PARAM_TYPE_PARAMETER_IN,
|
||
|
|
HV_PARAM_TYPE_PARAMETER_OUT,
|
||
|
|
HV_PARAM_TYPE_EVENT_IN,
|
||
|
|
HV_PARAM_TYPE_EVENT_OUT
|
||
|
|
} HvParameterType;
|
||
|
|
|
||
|
|
typedef struct HvParameterInfo {
|
||
|
|
const char *name; // the human readable parameter name
|
||
|
|
hv_uint32_t hash; // an integer identified used by heavy for this parameter
|
||
|
|
HvParameterType type; // type of this parameter
|
||
|
|
float minVal; // the minimum value of this parameter
|
||
|
|
float maxVal; // the maximum value of this parameter
|
||
|
|
float defaultVal; // the default value of this parameter
|
||
|
|
} HvParameterInfo;
|
||
|
|
|
||
|
|
typedef void (HvSendHook_t) (HeavyContextInterface *context, const char *sendName, hv_uint32_t sendHash, const HvMessage *msg);
|
||
|
|
typedef void (HvPrintHook_t) (HeavyContextInterface *context, const char *printName, const char *str, const HvMessage *msg);
|
||
|
|
|
||
|
|
#endif // _HEAVY_DECLARATIONS_
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
class HeavyContextInterface {
|
||
|
|
|
||
|
|
public:
|
||
|
|
HeavyContextInterface() {}
|
||
|
|
virtual ~HeavyContextInterface() {};
|
||
|
|
|
||
|
|
/** Returns the read-only user-assigned name of this patch. */
|
||
|
|
virtual const char *getName() = 0;
|
||
|
|
|
||
|
|
/** Returns the number of input channels with which this context has been configured. */
|
||
|
|
virtual int getNumInputChannels() = 0;
|
||
|
|
|
||
|
|
/** Returns the number of output channels with which this context has been configured. */
|
||
|
|
virtual int getNumOutputChannels() = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns the total size in bytes of the context.
|
||
|
|
* This value may change if tables are resized.
|
||
|
|
*/
|
||
|
|
virtual int getSize() = 0;
|
||
|
|
|
||
|
|
/** Returns the sample rate with which this context has been configured. */
|
||
|
|
virtual double getSampleRate() = 0;
|
||
|
|
|
||
|
|
/** Returns the current patch time in samples. This value is always exact. */
|
||
|
|
virtual hv_uint32_t getCurrentSample() = 0;
|
||
|
|
virtual float samplesToMilliseconds(hv_uint32_t numSamples) = 0;
|
||
|
|
|
||
|
|
/** Converts milliseconds to samples. Input is limited to non-negative range. */
|
||
|
|
virtual hv_uint32_t millisecondsToSamples(float ms) = 0;
|
||
|
|
|
||
|
|
/** Sets a user-definable value. This value is never manipulated by Heavy. */
|
||
|
|
virtual void setUserData(void *x) = 0;
|
||
|
|
|
||
|
|
/** Returns the user-defined data. */
|
||
|
|
virtual void *getUserData() = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set the send hook. The function is called whenever a message is sent to any send object.
|
||
|
|
* Messages returned by this function should NEVER be freed. If the message must persist, call
|
||
|
|
* hv_msg_copy() first.
|
||
|
|
*/
|
||
|
|
virtual void setSendHook(HvSendHook_t *f) = 0;
|
||
|
|
|
||
|
|
/** Returns the send hook, or NULL if unset. */
|
||
|
|
virtual HvSendHook_t *getSendHook() = 0;
|
||
|
|
|
||
|
|
/** Set the print hook. The function is called whenever a message is sent to a print object. */
|
||
|
|
virtual void setPrintHook(HvPrintHook_t *f) = 0;
|
||
|
|
|
||
|
|
/** Returns the print hook, or NULL if unset. */
|
||
|
|
virtual HvPrintHook_t *getPrintHook() = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Processes one block of samples for a patch instance. The buffer format is an array of float channel arrays.
|
||
|
|
* If the context has not input or output channels, the respective argument may be NULL.
|
||
|
|
* The number of samples to to tbe processed should be a multiple of 1, 4, or 8, depending on if
|
||
|
|
* no, SSE or NEON, or AVX optimisation is being used, respectively.
|
||
|
|
* e.g. [[LLLL][RRRR]]
|
||
|
|
*
|
||
|
|
* @return The number of samples processed.
|
||
|
|
*
|
||
|
|
* This function is NOT thread-safe. It is assumed that only the audio thread will execute this function.
|
||
|
|
*/
|
||
|
|
virtual int process(float **inputBuffers, float **outputBuffer, int n) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Processes one block of samples for a patch instance. The buffer format is an uninterleaved float array of channels.
|
||
|
|
* If the context has not input or output channels, the respective argument may be NULL.
|
||
|
|
* The number of samples to to tbe processed should be a multiple of 1, 4, or 8, depending on if
|
||
|
|
* no, SSE or NEON, or AVX optimisation is being used, respectively.
|
||
|
|
* e.g. [LLLLRRRR]
|
||
|
|
*
|
||
|
|
* @return The number of samples processed.
|
||
|
|
*
|
||
|
|
* This function is NOT thread-safe. It is assumed that only the audio thread will execute this function.
|
||
|
|
*/
|
||
|
|
virtual int processInline(float *inputBuffers, float *outputBuffer, int n) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Processes one block of samples for a patch instance. The buffer format is an interleaved float array of channels.
|
||
|
|
* If the context has not input or output channels, the respective argument may be NULL.
|
||
|
|
* The number of samples to to tbe processed should be a multiple of 1, 4, or 8, depending on if
|
||
|
|
* no, SSE or NEON, or AVX optimisation is being used, respectively.
|
||
|
|
* e.g. [LRLRLRLR]
|
||
|
|
*
|
||
|
|
* @return The number of samples processed.
|
||
|
|
*
|
||
|
|
* This function is NOT thread-safe. It is assumed that only the audio thread will execute this function.
|
||
|
|
*/
|
||
|
|
virtual int processInlineInterleaved(float *inputBuffers, float *outputBuffer, int n) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Sends a formatted message to a receiver that can be scheduled for the future.
|
||
|
|
* The receiver is addressed with its hash, which can also be determined using hv_stringToHash().
|
||
|
|
* This function is thread-safe.
|
||
|
|
*
|
||
|
|
* @return True if the message was accepted. False if the message could not fit onto
|
||
|
|
* the message queue to be processed this block.
|
||
|
|
*/
|
||
|
|
virtual bool sendMessageToReceiver(hv_uint32_t receiverHash, double delayMs, HvMessage *m) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Sends a formatted message to a receiver that can be scheduled for the future.
|
||
|
|
* The receiver is addressed with its hash, which can also be determined using hv_stringToHash().
|
||
|
|
* This function is thread-safe.
|
||
|
|
*
|
||
|
|
* @return True if the message was accepted. False if the message could not fit onto
|
||
|
|
* the message queue to be processed this block.
|
||
|
|
*/
|
||
|
|
virtual bool sendMessageToReceiverV(hv_uint32_t receiverHash, double delayMs, const char *fmt, ...) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A convenience function to send a float to a receiver to be processed immediately.
|
||
|
|
* The receiver is addressed with its hash, which can also be determined using hv_stringToHash().
|
||
|
|
* This function is thread-safe.
|
||
|
|
*
|
||
|
|
* @return True if the message was accepted. False if the message could not fit onto
|
||
|
|
* the message queue to be processed this block.
|
||
|
|
*/
|
||
|
|
virtual bool sendFloatToReceiver(hv_uint32_t receiverHash, float f) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A convenience function to send a bang to a receiver to be processed immediately.
|
||
|
|
* The receiver is addressed with its hash, which can also be determined using hv_stringToHash().
|
||
|
|
* This function is thread-safe.
|
||
|
|
*
|
||
|
|
* @return True if the message was accepted. False if the message could not fit onto
|
||
|
|
* the message queue to be processed this block.
|
||
|
|
*/
|
||
|
|
virtual bool sendBangToReceiver(hv_uint32_t receiverHash) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* A convenience function to send a symbol to a receiver to be processed immediately.
|
||
|
|
* The receiver is addressed with its hash, which can also be determined using hv_stringToHash().
|
||
|
|
* This function is thread-safe.
|
||
|
|
*
|
||
|
|
* @return True if the message was accepted. False if the message could not fit onto
|
||
|
|
* the message queue to be processed this block.
|
||
|
|
*/
|
||
|
|
virtual bool sendSymbolToReceiver(hv_uint32_t receiverHash, const char *symbol) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Cancels a previously scheduled message.
|
||
|
|
*
|
||
|
|
* @param sendMessage May be NULL.
|
||
|
|
*/
|
||
|
|
virtual bool cancelMessage(HvMessage *m, void (*sendMessage)(HeavyContextInterface *, int, const HvMessage *)=nullptr) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns information about each parameter such as name, hash, and range.
|
||
|
|
* The total number of parameters is always returned.
|
||
|
|
*
|
||
|
|
* @param index The parameter index.
|
||
|
|
* @param info A pointer to a HvParameterInfo struct. May be null.
|
||
|
|
*
|
||
|
|
* @return The total number of parameters.
|
||
|
|
*/
|
||
|
|
virtual int getParameterInfo(int index, HvParameterInfo *info) = 0;
|
||
|
|
|
||
|
|
/** Returns a pointer to the raw buffer backing this table. DO NOT free it. */
|
||
|
|
virtual float *getBufferForTable(hv_uint32_t tableHash) = 0;
|
||
|
|
|
||
|
|
/** Returns the length of this table in samples. */
|
||
|
|
virtual int getLengthForTable(hv_uint32_t tableHash) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Resizes the table to the given length.
|
||
|
|
*
|
||
|
|
* Existing contents are copied to the new table. Remaining space is cleared
|
||
|
|
* if the table is longer than the original, truncated otherwise.
|
||
|
|
*
|
||
|
|
* @param tableHash The table identifier.
|
||
|
|
* @param newSampleLength The new length of the table, in samples.
|
||
|
|
*
|
||
|
|
* @return False if the table could not be found. True otherwise.
|
||
|
|
*/
|
||
|
|
virtual bool setLengthForTable(hv_uint32_t tableHash, hv_uint32_t newSampleLength) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Acquire the input message queue lock.
|
||
|
|
*
|
||
|
|
* This function will block until the message lock as been acquired.
|
||
|
|
* Typical applications will not require the use of this function.
|
||
|
|
*/
|
||
|
|
virtual void lockAcquire() = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Try to acquire the input message queue lock.
|
||
|
|
*
|
||
|
|
* If the lock has been acquired, hv_lock_release() must be called to release it.
|
||
|
|
* Typical applications will not require the use of this function.
|
||
|
|
*
|
||
|
|
* @return Returns true if the lock has been acquired, false otherwise.
|
||
|
|
*/
|
||
|
|
virtual bool lockTry() = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Release the input message queue lock.
|
||
|
|
*
|
||
|
|
* Typical applications will not require the use of this function.
|
||
|
|
*/
|
||
|
|
virtual void lockRelease() = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set the size of the input message queue in kilobytes.
|
||
|
|
*
|
||
|
|
* The buffer is reset and all existing contents are lost on resize.
|
||
|
|
*
|
||
|
|
* @param inQueueKb Must be positive i.e. at least one.
|
||
|
|
*/
|
||
|
|
virtual void setInputMessageQueueSize(int inQueueKb) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Set the size of the output message queue in kilobytes.
|
||
|
|
*
|
||
|
|
* The buffer is reset and all existing contents are lost on resize.
|
||
|
|
* Only the default sendhook uses the outgoing message queue. If the default
|
||
|
|
* sendhook is not being used, then this function is not useful.
|
||
|
|
*
|
||
|
|
* @param outQueueKb Must be postive i.e. at least one.
|
||
|
|
*/
|
||
|
|
virtual void setOutputMessageQueueSize(int outQueueKb) = 0;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Get the next message in the outgoing queue, will also consume the message.
|
||
|
|
* Returns false if there are no messages.
|
||
|
|
*
|
||
|
|
* @param destinationHash a hash of the name of the receiver the message was sent to.
|
||
|
|
* @param outMsg message pointer that is filled by the next message contents.
|
||
|
|
* @param msgLengthBytes max length of outMsg in bytes.
|
||
|
|
*
|
||
|
|
* @return True if there is a message in the outgoing queue.
|
||
|
|
*/
|
||
|
|
virtual bool getNextSentMessage(hv_uint32_t *destinationHash, HvMessage *outMsg, hv_size_t msgLengthBytes) = 0;
|
||
|
|
|
||
|
|
/** Returns a 32-bit hash of any string. Returns 0 if string is NULL. */
|
||
|
|
static hv_uint32_t getHashForString(const char *str);
|
||
|
|
};
|
||
|
|
|
||
|
|
#endif // _HEAVY_CONTEXT_INTERFACE_H_
|