<commit_before>/* FluidSynth - A Software Synthesizer
 *
 * Copyright (C) 2003  <NAME> and others.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *  
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA
 */

#ifndef _FLUIDSYNTH_SFONT_H
#define _FLUIDSYNTH_SFONT_H

#ifdef __cplusplus
extern "C" {
#endif


/**
 * @file sfont.h
 * @brief SoundFont plugins
 *
 * It is possible to add new SoundFont loaders to the
 * synthesizer. The API uses a couple of "interfaces" (structures
 * with callback functions): #fluid_sfloader_t, #fluid_sfont_t, and
 * #fluid_preset_t.  This API allows for virtual SoundFont files to be loaded
 * and synthesized, which may not actually be SoundFont files, as long as they
 * can be represented by the SoundFont synthesis model.
 *
 * To add a new SoundFont loader to the synthesizer, call
 * fluid_synth_add_sfloader() and pass a pointer to an
 * fluid_sfloader_t structure. The important callback function in
 * this structure is "load", which should try to load a file and
 * returns a #fluid_sfont_t structure, or NULL if it fails.
 *
 * The #fluid_sfont_t structure contains a callback to obtain the
 * name of the SoundFont. It contains two functions to iterate
 * though the contained presets, and one function to obtain a
 * preset corresponding to a bank and preset number. This
 * function should return a #fluid_preset_t structure.
 *
 * The #fluid_preset_t structure contains some functions to obtain
 * information from the preset (name, bank, number). The most
 * important callback is the noteon function. The noteon function
 * should call fluid_synth_alloc_voice() for every sample that has
 * to be played. fluid_synth_alloc_voice() expects a pointer to a
 * #fluid_sample_t structure and returns a pointer to the opaque
 * #fluid_voice_t structure. To set or increment the values of a
 * generator, use fluid_voice_gen_set() or fluid_voice_gen_incr(). When you are
 * finished initializing the voice call fluid_voice_start() to
 * start playing the synthesis voice.
 */

/**
 * Some notification enums for presets and samples.
 */
enum {
  FLUID_PRESET_SELECTED,                /**< Preset selected notify */
  FLUID_PRESET_UNSELECTED,              /**< Preset unselected notify */
  FLUID_SAMPLE_DONE                     /**< Sample no longer needed notify */
};

/**
 * Indicates the type of a sample used by the _fluid_sample_t::sampletype field.
 */
enum fluid_sample_type
{
    FLUID_SAMPLETYPE_MONO = 0x1, /**< Used for mono samples */
    FLUID_SAMPLETYPE_RIGHT = 0x2, /**< Used for right samples of a stereo pair */
    FLUID_SAMPLETYPE_LEFT = 0x4, /**< Used for left samples of a stereo pair */
    FLUID_SAMPLETYPE_LINKED = 0x8, /**< Currently not used */
    FLUID_SAMPLETYPE_OGG_VORBIS = 0x10, /**< Used for Ogg Vorbis compressed samples @since 1.1.7 */
    FLUID_SAMPLETYPE_ROM = 0x8000 /**< Indicates ROM samples, causes sample to be ignored */
};

/**
 * SoundFont loader structure.
 */
struct _fluid_sfloader_t {
  void* data;           /**< User defined data pointer used by _fluid_sfloader_t::load() */

  /** Callback structure specifying file operations used during soundfont loading to allow custom loading, such as from memory */
  const fluid_file_callbacks_t* file_callbacks;

  /**                                                                                                                                                                                                                               
   * The free method should free the memory allocated for this loader instance in
   * addition to any private data.
   * @param loader SoundFont loader
   */
  void (*free)(fluid_sfloader_t* loader);

  /**
   * Method to load an instrument file (does not actually need to be a real file name,
   * could be another type of string identifier that the \a loader understands).
   * @param loader SoundFont loader
   * @param filename File name or other string identifier
   * @return The loaded instrument file (SoundFont) or NULL if an error occured.
   */
  fluid_sfont_t* (*load)(fluid_sfloader_t* loader, const char* filename);
};

/**
 * File callback structure to enable custom soundfont loading (e.g. from memory).
 */
struct _fluid_file_callbacks_t {
  /**
   * Opens the file or memory indicated by \c filename in binary read mode.
   * \c filename matches the one provided during the fluid_synth_sfload() call.
   *
   * @return returns a file handle on success, NULL otherwise
   */
  void * (* fopen )(const char * filename);

  /**
   * Reads \c count bytes to the specified buffer \c buf.
   * 
   * @return returns #FLUID_OK if exactly \c count bytes were successfully read, else #FLUID_FAILED
   */
  int (* fread )(void *buf, int count, void * handle);

  /**
   * Same purpose and behaviour as fseek.
   * 
   * @param origin either \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
   * 
   * @return returns #FLUID_OK if the seek was successfully performed while not seeking beyond a buffer or file, #FLUID_FAILED otherwise */
  int (* fseek )(void * handle, long offset, int origin);

  /** 
   * Closes the handle and frees used ressources.
   * 
   * @return returns #FLUID_OK on success, #FLUID_FAILED on error */
  int (* fclose)(void * handle);

  /** @return returns current file offset or #FLUID_FAILED on error */
  long (* ftell )(void * handle);
};


FLUIDSYNTH_API fluid_sfloader_t* new_fluid_defsfloader(fluid_settings_t* settings);

/*
 * Virtual SoundFont instance structure.
 */
struct _fluid_sfont_t {
  void* data;           /**< User defined data */
  unsigned int id;      /**< SoundFont ID */

  /**
   * Method to free a virtual SoundFont bank.<commit_msg>make sure doxygen recognizes struct _fluid_sfont_t<commit_after>/* FluidSynth - A Software Synthesizer
 *
 * Copyright (C) 2003  <NAME> and others.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *  
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA
 */

#ifndef _FLUIDSYNTH_SFONT_H
#define _FLUIDSYNTH_SFONT_H

#ifdef __cplusplus
extern "C" {
#endif


/**
 * @file sfont.h
 * @brief SoundFont plugins
 *
 * It is possible to add new SoundFont loaders to the
 * synthesizer. The API uses a couple of "interfaces" (structures
 * with callback functions): #fluid_sfloader_t, #fluid_sfont_t, and
 * #fluid_preset_t.  This API allows for virtual SoundFont files to be loaded
 * and synthesized, which may not actually be SoundFont files, as long as they
 * can be represented by the SoundFont synthesis model.
 *
 * To add a new SoundFont loader to the synthesizer, call
 * fluid_synth_add_sfloader() and pass a pointer to an
 * fluid_sfloader_t structure. The important callback function in
 * this structure is "load", which should try to load a file and
 * returns a #fluid_sfont_t structure, or NULL if it fails.
 *
 * The #fluid_sfont_t structure contains a callback to obtain the
 * name of the SoundFont. It contains two functions to iterate
 * though the contained presets, and one function to obtain a
 * preset corresponding to a bank and preset number. This
 * function should return a #fluid_preset_t structure.
 *
 * The #fluid_preset_t structure contains some functions to obtain
 * information from the preset (name, bank, number). The most
 * important callback is the noteon function. The noteon function
 * should call fluid_synth_alloc_voice() for every sample that has
 * to be played. fluid_synth_alloc_voice() expects a pointer to a
 * #fluid_sample_t structure and returns a pointer to the opaque
 * #fluid_voice_t structure. To set or increment the values of a
 * generator, use fluid_voice_gen_set() or fluid_voice_gen_incr(). When you are
 * finished initializing the voice call fluid_voice_start() to
 * start playing the synthesis voice.
 */

/**
 * Some notification enums for presets and samples.
 */
enum {
  FLUID_PRESET_SELECTED,                /**< Preset selected notify */
  FLUID_PRESET_UNSELECTED,              /**< Preset unselected notify */
  FLUID_SAMPLE_DONE                     /**< Sample no longer needed notify */
};

/**
 * Indicates the type of a sample used by the _fluid_sample_t::sampletype field.
 */
enum fluid_sample_type
{
    FLUID_SAMPLETYPE_MONO = 0x1, /**< Used for mono samples */
    FLUID_SAMPLETYPE_RIGHT = 0x2, /**< Used for right samples of a stereo pair */
    FLUID_SAMPLETYPE_LEFT = 0x4, /**< Used for left samples of a stereo pair */
    FLUID_SAMPLETYPE_LINKED = 0x8, /**< Currently not used */
    FLUID_SAMPLETYPE_OGG_VORBIS = 0x10, /**< Used for Ogg Vorbis compressed samples @since 1.1.7 */
    FLUID_SAMPLETYPE_ROM = 0x8000 /**< Indicates ROM samples, causes sample to be ignored */
};

/**
 * SoundFont loader structure.
 */
struct _fluid_sfloader_t {
  void* data;           /**< User defined data pointer used by _fluid_sfloader_t::load() */

  /** Callback structure specifying file operations used during soundfont loading to allow custom loading, such as from memory */
  const fluid_file_callbacks_t* file_callbacks;

  /**                                                                                                                                                                                                                               
   * The free method should free the memory allocated for this loader instance in
   * addition to any private data.
   * @param loader SoundFont loader
   */
  void (*free)(fluid_sfloader_t* loader);

  /**
   * Method to load an instrument file (does not actually need to be a real file name,
   * could be another type of string identifier that the \a loader understands).
   * @param loader SoundFont loader
   * @param filename File name or other string identifier
   * @return The loaded instrument file (SoundFont) or NULL if an error occured.
   */
  fluid_sfont_t* (*load)(fluid_sfloader_t* loader, const char* filename);
};

/**
 * File callback structure to enable custom soundfont loading (e.g. from memory).
 */
struct _fluid_file_callbacks_t {
  /**
   * Opens the file or memory indicated by \c filename in binary read mode.
   * \c filename matches the one provided during the fluid_synth_sfload() call.
   *
   * @return returns a file handle on success, NULL otherwise
   */
  void * (* fopen )(const char * filename);

  /**
   * Reads \c count bytes to the specified buffer \c buf.
   * 
   * @return returns #FLUID_OK if exactly \c count bytes were successfully read, else #FLUID_FAILED
   */
  int (* fread )(void *buf, int count, void * handle);

  /**
   * Same purpose and behaviour as fseek.
   * 
   * @param origin either \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
   * 
   * @return returns #FLUID_OK if the seek was successfully performed while not seeking beyond a buffer or file, #FLUID_FAILED otherwise */
  int (* fseek )(void * handle, long offset, int origin);

  /** 
   * Closes the handle and frees used ressources.
   * 
   * @return returns #FLUID_OK on success, #FLUID_FAILED on error */
  int (* fclose)(void * handle);

  /** @return returns current file offset or #FLUID_FAILED on error */
  long (* ftell )(void * handle);
};


FLUIDSYNTH_API fluid_sfloader_t* new_fluid_defsfloader(fluid_settings_t* settings);

/**
 * Virtual SoundFont instance structure.
 */
struct _fluid_sfont_t {
  void* data;           /**< User defined data */
  unsigned int id;      /**< SoundFont ID */

  /**
   * Method to free a virtual SoundFont bank.
{'fraction_non_alphanumeric': 0.07671038078685416, 'fraction_numerical': 0.005688102385842945, 'mean_word_length': 3.052176696542894, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 22, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2943071', 'n_tokens_mistral': 3618, 'n_tokens_neox': 3489, 'n_words': 1512}