HeavyContextInterface.hpp

/**
 * Copyright (c) 2016 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_