"""Structures.""" # pylint: disable=too-few-public-methods # These are mostly data containers, really. # pylint: disable=attribute-defined-outside-init # ctype Structures can do this magic! # pylint: disable=invalid-name # Just staying close to the original names here. from ctypes import * from .callback_prototypes import * from .enums import OUTPUT_METHOD from .function_prototypes import * from .structure_declarations import * GUID._fields_ = [ ("data1", c_uint), ("data2", c_ushort), ("data3", c_ushort), ( "data4", c_char * 8, ), ] class ADVANCEDSETTINGS(Structure): """Advanced configuration settings. Structure to allow configuration of lesser used system level settings. These tweaks generally allow the user to set resource limits and customize settings to better fit their application. All members have a default of 0 except for `cbSize`, so clearing the whole structure to zeroes first then setting cbSize is a common use pattern. Specifying one of the codec maximums will help determine the maximum CPU usage of playing :py:attr:`~pyfmodex.flags.MODE.CREATECOMPRESSEDSAMPLE` Sounds of that type as well as the memory requirements. Memory will be allocated for 'up front' (during :py:meth:`~pyfmodex.system.System.init`) if these values are specified as non zero. If any are zero, it allocates memory for the codec whenever a file of the type in question is loaded. So if maxMPEGCodecs is 0 for example, it will allocate memory for the MPEG codecs the first time an MP3 is loaded or an MP3 based .FSB file is loaded. Setting `DSPBufferPoolSize` will pre-allocate memory for the FMOD DSP network. By default eight buffers are created up front. A large network might require more if the aim is to avoid real-time allocations from the FMOD mixer thread. :ivar int cbsize: Size of this structure. Must be set to sizeof(`ADVANCEDSETTINGS`) before calling setting or requesting :py:attr:`~pyfmodex.system.System.advanced_settings`. :ivar int maxMPEGcodecs: Maximum MPEG Sounds created as :py:attr:`~pyfmodex.flags.MODE.CREATECOMPRESSEDSAMPLE`. :ivar int maxADPCMcodecs: Maximum IMA-ADPCM Sounds created as :py:attr:`~pyfmodex.flags.MODE.CREATECOMPRESSEDSAMPLE`. :ivar int maxXMAcodecs: Maximum XMA Sounds created as :py:attr:`~pyfmodex.flags.MODE.CREATECOMPRESSEDSAMPLE`. :ivar int maxVorbisCodecs: Maximum Vorbis Sounds created as :py:attr:`~pyfmodex.flags.MODE.CREATECOMPRESSEDSAMPLE`. :ivar int maxAT9Codecs: Maximum AT9 Sounds created as :py:attr:`~pyfmodex.flags.MODE.CREATECOMPRESSEDSAMPLE`. :ivar int maxFADPCMCodecs: Maximum FADPCM Sounds created as :py:attr:`~pyfmodex.flags.MODE.CREATECOMPRESSEDSAMPLE`. :ivar int maxPCMcodecs: Deprecated. :ivar int ASIONumChannels: Number of elements in `ASIOSpeakerList` on input, number of elements in `ASIOChannelList` on output. :ivar str ASIOChannelList: Read only list of strings representing ASIO channel names, count is defined by `ASIONumChannels`. Only valid after :py:meth:`~pyfmodex.system.System.init`. :ivar SPEAKER ASIOSpeakerList: List of speakers that represent each ASIO channel used for remapping, count is defined by `ASIONumChannels`. Use :py:attr:`~pyfmodex.enums.SPEAKER.NONE` to indicate no output for a given speaker. :ivar float vol0virtualvol: For use with :py:attr:`~pyfmodex.flags.INIT_FLAGS.VOL0_BECOMES_VIRTUAL`, :py:class:`Channels ` with audibility below this will become virtual. :ivar int defaultDecodeBufferSize: For use with Streams, the default size of the double buffer. :ivar int profileport: For use with :py:attr:`~pyfmodex.flags.INIT_FLAGS.PROFILE_ENABLE`, specify the port to listen on for connections by FMOD Studio or FMOD Profiler. :ivar int geometryMaxFadeTime: For use with :py:class:`~pyfmodex.geometry.Geometry`, the maximum time it takes for a :py:class:`~pyfmodex.channel.Channel` to fade to the new volume level when its occlusion changes. :ivar float distanceFilterCenterFreq: For use with :py:attr:`~pyfmodex.flags.INIT_FLAGS.CHANNEL_DISTANCEFILTER`, the default center frequency for the distance filtering effect. :ivar int reverb3Dinstance: For use with :py:class:`~pyfmodex.reverb.Reverb3D`, selects which global reverb instance to use. :ivar int DSPBufferPoolSize: Number of intermediate mixing buffers in the 'DSP buffer pool'. Each buffer in bytes will be `bufferlength` (See :py:attr:`~pyfmodex.system.System.dsp_buffer_size`) * sizeof(float) * output mode speaker count (See :py:class:`~pyfmodex.enums.SPEAKERMODE`). ie 7.1 @ 1024 DSP block size = 1024 * 4 * 8 = 32KB. :ivar DSP_RESAMPLER resamplerMethod: Resampling method used by :py:class:`Channels `. :ivar int randomSeed: Seed value to initialize the internal random number generator. :ivar int maxConvolutionThreads: Maximum number of CPU threads to use for :py:class:`~pyfmodex.enums.DSP_CONVOLUTIONREVERB` effect. 1 = effect is entirely processed inside the THREAD_TYPE_MIXER thread. 2 and 3 offloads different parts of the convolution processing into different threads (THREAD_TYPE_CONVOLUTION1 and FMOD_THREAD_TYPE_CONVOLUTION2 to increase throughput. """ _fields_ = [ ("cbsize", c_int), ("maxMPEGcodecs", c_int), ("maxADPCMcodecs", c_int), ("maxXMAcodecs", c_int), ("maxVorbisCodecs", c_int), ("maxAT9Codecs", c_int), ("maxFADPCMCodecs", c_int), ("maxPCMcodecs", c_int), ("ASIONumChannels", c_int), ("ASIOChannelList", POINTER(c_char_p)), ("ASIOSpeakerList", POINTER(c_int)), ("vol0virtualvol", c_float), ("defaultDecodeBufferSize", c_uint), ("profileport", c_ushort), ("geometryMaxFadeTime", c_uint), ("distanceFilterCenterFreq", c_float), ("reverb3Dinstance", c_int), ("DSPBufferPoolSize", c_int), ("resamplerMethod", c_int), ("randomSeed", c_uint), ("maxConvolutionThreads", c_int), ] def __init__(self, *args, **kwargs): Structure.__init__(self, *args, **kwargs) self.cbsize = sizeof(self) ASYNCREADINFO._fields_ = [ ("handle", c_void_p), ("offset", c_uint), ("sizebytes", c_uint), ("priority", c_int), ("userdata", c_void_p), ("buffer", c_void_p), ("bytesread", c_uint), ("done", FILE_ASYNCDONE_FUNC), ] class CODEC_DESCRIPTION(Structure): """Codec description. This description structure allows the plugin writer to define all functionality required for a user defined codec. :ivar str name: Name of the codec. :ivar int version: Plugin writer's version number. :ivar int defaultasstream: Defaults as stream. :ivar TIMEUNIT timeunits: Time units used with setposition codec. :ivar CODEC_OPEN_CALLBACK open: Open callback. :ivar CODEC_CLOSE_CALLBACK close: Close callback. :ivar CODEC_READ_CALLBACK read: Read callback. :ivar CODEC_GETLENGTH_CALLBACK getlength: Get length callback. :ivar CODEC_SETPOSITION_CALLBACK setposition: Seek callback. :ivar CODEC_GETPOSITION_CALLBACK getposition: Get position callback. :ivar CODEC_SOUNDCREATE_CALLBACK soundcreate: Sound creation callback. :ivar CODEC_GETWAVEFORMAT_CALLBACK getwaveformat: Get wave format callback. """ _fields_ = [ ("name", c_char_p), ("version", c_uint), ("defaultasstream", c_int), ("timeunits", c_int), ("open", CODEC_OPEN_CALLBACK), ("close", CODEC_CLOSE_CALLBACK), ("read", CODEC_READ_CALLBACK), ("getlength", CODEC_GETLENGTH_CALLBACK), ("setposition", CODEC_SETPOSITION_CALLBACK), ("getposition", CODEC_GETPOSITION_CALLBACK), ("soundcreate", CODEC_SOUNDCREATE_CALLBACK), ("getwaveformat", CODEC_GETWAVEFORMAT_CALLBACK), ] CODEC_WAVEFORMAT._fields_ = [ ("name", c_char_p), ("format", c_int), ("channels", c_int), ("frequency", c_int), ("lengthbytes", c_uint), ("lengthpcm", c_uint), ("pcmblocksize", c_uint), ("loopstart", c_int), ("loopend", c_int), ("mode", c_int), ("channelmask", c_int), ("channelorder", c_int), ("peakvolume", c_float), ] CODEC_STATE._fields_ = [ ("numsubsounds", c_int), ("waveformat", CODEC_WAVEFORMAT), ("plugindata", c_void_p), ("filehandle", c_void_p), ("filesize", c_uint), ("fileread", FILE_READ_CALLBACK), ("fileseek", FILE_SEEK_CALLBACK), ("metadata", CODEC_METADATA_CALLBACK), ("waveformatversion", c_int), ] COMPLEX._fields_ = [("real", c_float), ("imag", c_float)] CREATESOUNDEXINFO._fields_ = [ ("cbsize", c_int), ("length", c_uint), ("fileoffset", c_uint), ("numchannels", c_int), ("defaultfrequency", c_int), ("format", c_int), ("decodebuffersize", c_uint), ("initialsubsound", c_int), ("numsubsounds", c_int), ("inclusionlist", POINTER(c_int)), ("inclusionlistnum", c_int), ("pcmreadcallback", SOUND_PCMREADCALLBACK), ("pcmsetposcallback", SOUND_PCMSETPOSCALLBACK), ("nonblockcallback", SOUND_NONBLOCKCALLBACK), ("dlsname", c_char_p), ("encryptionkey", c_char_p), ("maxpolyphony", c_int), ("userdata", c_void_p), ("suggestedsoundtype", c_int), ("useropen", FILE_OPEN_CALLBACK), ("userclose", FILE_CLOSE_CALLBACK), ("userread", FILE_READ_CALLBACK), ("userseek", FILE_SEEK_CALLBACK), ("userasyncread", FILE_ASYNCREAD_CALLBACK), ("userasynccancel", FILE_ASYNCCANCEL_CALLBACK), ("fileuserdata", c_void_p), ("filebuffersize", c_int), ("channelorder", c_int), ("initialsoundgroup", c_void_p), ("initialseekposition", c_uint), ("initialseekpostype", c_int), ("ignoresetfilesystem", c_int), ("audioqueuepolicy", c_uint), ("minmidigranularity", c_uint), ("nonblockthreadid", c_int), ("fsbguid", POINTER(GUID)), ] def exinfo_init(self, *args, **kwargs): """Constructor for the CREATESOUNDEXINFO structure. Determines and stores its own size. """ Structure.__init__(self, *args, **kwargs) self.cbsize = sizeof(self) CREATESOUNDEXINFO.__init__ = exinfo_init class VECTOR(Structure): """Structure describing a point in 3D space. FMOD uses a left handed coordinate system by default. To use a right handed coordinate system specify :py:attr:`~pyfmodex.flags.INIT_FLAGS.THREED_RIGHTHANDED` in :py:meth:`~pyfmodex.system.System.init`. :ivar float x: X coordinate in 3D space. :ivar float y: Y coordinate in 3D space. :ivar float z: Z coordinate in 3D space. """ _fields_ = [("x", c_float), ("y", c_float), ("z", c_float)] @staticmethod def from_list(lst): """Instantiate a VECTOR from a list with three coordinate floats.""" vec = VECTOR() vec.x = lst[0] vec.y = lst[1] vec.z = lst[2] return vec def to_list(self): """The VECTOR as a list of three coordinate floats.""" return [self.x, self.y, self.z] THREED_ATTRIBUTES._fields_ = [ ("position", VECTOR), ("velocity", VECTOR), ("forward", VECTOR), ("up", VECTOR), ] DSP_BUFFER_ARRAY._fields_ = [ ("numbuffers", c_int), ("buffernumchannels", POINTER(c_int)), ("bufferchannelmask", POINTER(c_int)), ("buffers", POINTER(POINTER(c_float))), ("speakermode", c_int), ] class DSP_METERING_INFO(Structure): """DSP metering info. :ivar int numsamples: Number of samples considered for this metering info. :ivar list(float) peaklevel: Peak level per channel. :ivar list(float) rmslevel: Rms level per channel. :ivar float numchannels: Number of channels. """ _fields_ = [ ("numsamples", c_int), ("peaklevel", c_float * 32), ("rmslevel", c_float * 32), ("numchannels", c_short), ] class DSP_PARAMETER_3DATTRIBUTES(Structure): """3D attributes data structure. The :py:class:`~pyfmodex.studio.system.StudioSystem` will set this parameter automatically if an :py:class:`~pyfmodex.studio.event_instance.EventInstance` position changes, however if using the core :py:class:`~pyfmodex.system.System` you must set this DSP parameter explicitly. Attributes must use a coordinate system with the positive Y axis being up and the positive X axis being right. FMOD will convert passed in coordinates to left-handed for the plugin if the System was initialized with the :py:attr:`~pyfmodex.flags.INIT_FLAGS.THREED_RIGHTHANDED` flag. When using a listener attenuation position, the direction of the `relative` attributes will be relative to the listener position and the length will be the distance to the attenuation position. :ivar THREED_ATTRIBUTES relative: Position of the sound relative to the listener. :ivar THREED_ATTRIBUTES absolute: Position of the sound in world coordinates. """ _fields_ = [("relative", THREED_ATTRIBUTES), ("absolute", THREED_ATTRIBUTES)] class DSP_PARAMETER_3DATTRIBUTES_MULTI(Structure): """3D attributes data structure for multiple listeners. The :py:class:`~pyfmodex.studio.system.StudioSystem` will set this parameter automatically if an :py:class:`~pyfmodex.studio.event_instance.EventInstance` position changes, however if using the core :py:class:`~pyfmodex.system.System` you must set this DSP parameter explicitly. Attributes must use a coordinate system with the positive Y axis being up and the positive X axis being right. FMOD will convert passed in coordinates to left-handed for the plugin if the System was initialized with the :py:attr:`~pyfmodex.flags.INIT_FLAGS.THREED_RIGHTHANDED` flag. When using a listener attenuation position, the direction of the `relative` attributes will be relative to the listener position and the length will be the distance to the attenuation position. :ivar int numlisteners: Number of listeners. :ivar THREED_ATTRIBUTES relative: Position of the sound relative to the listeners. :ivar list(float) weight: Weighting of the listeners where 0 means listener has no contribution and 1 means full contribution. :ivar THREED_ATTRIBUTES absolute: Position of the sound in world coordinates. """ _fields_ = [ ("numlisteners", c_int), ("relative", THREED_ATTRIBUTES * 8), ("weight", c_float * 8), ("absolute", THREED_ATTRIBUTES), ] class DSP_PARAMETER_DESC_BOOL(Structure): """Boolean parameter description. :ivar bool defaultval: Default parameter value. :ivar list(str) valuenames: Names for false and true, respectively. There should be two strings. """ _fields_ = [("defaultval", c_bool), ("valuenames", POINTER(c_char_p))] class DSP_PARAMETER_DESC_DATA(Structure): """Data parameter description. :ivar int datatype: Type of data. """ _fields_ = [("datatype", c_int)] class DSP_PARAMETER_FLOAT_MAPPING_PIECEWISE_LINEAR(Structure): """Structure to define a piecewise linear mapping. :ivar int numpoints: Number of pairs in the piecewise mapping (at least two). :ivar list(float) pointparamvalues: Values in the parameter's units for each point :ivar list(float) pointpositions: Positions along the control's scale (e.g. dial angle) corresponding to each parameter value. The range of this scale is arbitrary and all positions will be relative to the minimum and maximum values (e.g. [0,1,3] is equivalent to [1,2,4] and [2,4,8]). If this array is zero, pointparamvalues will be distributed with equal spacing. """ _fields_ = [ ("numpoints", c_int), ("pointparamvalues", POINTER(c_float)), ("pointpositions", POINTER(c_float)), ] class DSP_PARAMETER_FLOAT_MAPPING(Structure): """Structure to define a mapping for a DSP unit's float parameter. :ivar DSP_PARAMETER_FLOAT_MAPPING_TYPE type: Mapping type. :ivar DSP_PARAMETER_FLOAT_MAPPING_PIECEWISE_LINEAR piecewiselinearmapping: Piecewise linear mapping type. """ _fields_ = [ ("type", c_int), ("piecewiselinearmapping", DSP_PARAMETER_FLOAT_MAPPING_PIECEWISE_LINEAR), ] class DSP_PARAMETER_DESC_FLOAT(Structure): """Float parameter description. :ivar float min: Minimum value. :ivar float max: Maximum value. :ivar float defaultval: Default value. :ivar DSP_PARAMETER_FLOAT_MAPPING mapping: How the values are distributed across dials and automation curves. """ _fields_ = [ ("min", c_float), ("max", c_float), ("defaultval", c_float), ("mapping", DSP_PARAMETER_FLOAT_MAPPING), ] class DSP_PARAMETER_DESC_INT(Structure): """Integer parameter description. :ivar int min: Minimum value. :ivar int max: Maximum value. :ivar int defaultval: Default value. :ivar bool goestoinf: Whether the last value represents infiniy. :ivar list(str) valuenames: Names for each value. There should be as many strings as there are possible values (`max` - `min` + 1). """ _fields_ = [ ("min", c_int), ("max", c_int), ("defaultval", c_int), ("goestoinf", c_bool), ("valuenames", POINTER(c_char_p)), ] class DSP_PARAMETER_FFT(Structure): """FFT parameter data structure. Notes on the `spectrum` data member: - Values inside the float buffer are typically between 0 and 1.0. - Each top level array represents one PCM channel of data. - Address data as spectrum[channel][bin]. A bin is 1 fft window entry. - Only read/display half of the buffer typically for analysis as the 2nd half is usually the same data reversed due to the nature of the way FFT works. :ivar int length: Number of entries in this spectrum window. Divide this by the output rate to get the Hz per entry. :ivar int numchannels: Number of channels in spectrum. :ivar list(float) spectrum: Per channel spectrum arrays. """ _fields_ = [("length", c_int), ("numchannels", c_int), ("spectrum", POINTER(c_float) * 32)] class DSP_PARAMETER_OVERALLGAIN(Structure): """Overall gain parameter data structure. This parameter is read by the system to determine the effect's gain for voice virtualization. :ivar float linear_gain: Overall linear gain of the effect on the direct signal path. :ivar float linear_gain_additive: Additive gain, for parallel signal paths. """ _fields_ = [("linear_gain", c_float), ("linear_gain_additive", c_float)] class DSP_PARAMETER_SIDECHAIN(Structure): """Side chain parameter data structure. :ivar bool sidechainenable: Whether sidechains are enabled. """ _fields_ = [("sidechainenable", c_bool)] class DSP_STATE_DFT_FUNCTIONS(Structure): """Struct containing DFT functions to enable a plugin to perform optimized time-frequency domain conversion. :ivar DSP_DFT_FFTREAL_FUNC fftreal: Function for performing an FFT on a real signal. :ivar DSP_DFT_IFFTREAL_FUNC inversefftreal: Function for performing an inverse FFT to get a real signal. """ _fields_ = [ ("fftreal", DSP_DFT_FFTREAL_FUNC), ("inversefftreal", DSP_DFT_IFFTREAL_FUNC), ] class DSP_STATE_PAN_FUNCTIONS(Structure): """Struct containing panning helper functions for spatialization plugins. :ivar DSP_PAN_SUMMONOMATRIX_FUNC summonomatrix: TBD. :ivar DSP_PAN_SUMSTEREOMATRIX_FUNC sumstereomatrix: TBD. :ivar DSP_PAN_SUMSURROUNDMATRIX_FUNC sumsurroundmatrix: TBD. :ivar DSP_PAN_SUMMONOTOSURROUNDMATRIX_FUNC summonotosurroundmatrix: TBD. :ivar DSP_PAN_SUMSTEREOTOSURROUNDMATRIX_FUNC sumstereotosurroundmatrix: TBD. :ivar DSP_PAN_GETROLLOFFGAIN_FUNC getrolloffgain: TBD. """ _fields_ = [ ("summonomatrix", DSP_PAN_SUMMONOMATRIX_FUNC), ("sumstereomatrix", DSP_PAN_SUMSTEREOMATRIX_FUNC), ("sumsurroundmatrix", DSP_PAN_SUMSURROUNDMATRIX_FUNC), ("summonotosurroundmatrix", DSP_PAN_SUMMONOTOSURROUNDMATRIX_FUNC), ("sumstereotosurroundmatrix", DSP_PAN_SUMSTEREOTOSURROUNDMATRIX_FUNC), ("getrolloffgain", DSP_PAN_GETROLLOFFGAIN_FUNC), ] class DSP_STATE_FUNCTIONS(Structure): """Struct containing functions to give plugin developers the ability to query system state, access system level functionality and helpers. :ivar DSP_ALLOC_FUNC alloc: Function to allocate memory using the FMOD memory system. :ivar DSP_REALLOC_FUNC realloc: Function to reallocate memory using the FMOD memory system. :ivar DSP_FREE_FUNC free: Function to free memory allocated with :py:data:`~pyfmodex.function_prototypes.DSP_ALLOC_FUNC`. :ivar DSP_GETSAMPLERATE_FUNC getsamplerate: Function to query the system sample rate. :ivar DSP_GETBLOCKSIZE_FUNC getblocksize: Function to query the system block size, DSPs will be requested to process blocks of varying length up to this size. :ivar DSP_STATE_DFT_FUNCTIONS dft: Struct containing DFT functions to enable a plugin to perform optimized time-frequency domain conversion. :ivar DSP_STATE_PAN_FUNCTIONS pan: Struct containing panning helper functions for spatialization plugins. :ivar DSP_GETSPEAKERMODE_FUNC getspeakermode: Function to query the system speaker modes. One is the mixer's default speaker mode, the other is the output mode the system is downmixing or upmixing to. :ivar DSP_GETCLOCK_FUNC getclock: Function to get the clock of the current DSP, as well as the subset of the input buffer that contains the signal. :ivar DSP_GETLISTENERATTRIBUTES_FUNC getlistenerattributes: Callback for getting the absolute listener attributes set via the API. :ivar DSP_LOG_FUNC log: Function to write to the FMOD logging system. :ivar DSP_GETUSERDATA_FUNC getuserdata: Function to get the user data attached to this DSP. See :py:attr:`~pyfmodex.structures.DSP_DESCRIPTION.userdata`. """ _fields_ = [ ("alloc", DSP_ALLOC_FUNC), ("realloc", DSP_REALLOC_FUNC), ("free", DSP_FREE_FUNC), ("getsamplerate", DSP_GETSAMPLERATE_FUNC), ("getblocksize", DSP_GETBLOCKSIZE_FUNC), ("dft", POINTER(DSP_STATE_DFT_FUNCTIONS)), ("pan", POINTER(DSP_STATE_PAN_FUNCTIONS)), ("getspeakermode", DSP_GETSPEAKERMODE_FUNC), ("getclock", DSP_GETCLOCK_FUNC), ("getlistenerattributes", DSP_GETLISTENERATTRIBUTES_FUNC), ("log", DSP_LOG_FUNC), ("getuserdata", DSP_GETUSERDATA_FUNC), ] DSP_STATE._fields_ = [ ("instance", c_void_p), ("plugindata", c_void_p), ("channelmask", c_int), ("sourcespeakermode", c_int), ("sidechaindata", POINTER(c_float)), ("sidechainchannels", c_int), ("functions", POINTER(DSP_STATE_FUNCTIONS)), ("systemobject", c_int), ] class DSP_PARAMETER_DESC_UNION(Union): """ :ivar DSP_PARAMETER_DESC_FLOAT floatdesc: Floating point format description used when type is :py:attr:`~pyfmodex.enums.DSP_PARAMETER_TYPE.FLOAT`. :ivar DSP_PARAMETER_DESC_INT intdesc: Integer format description used when type is :py:attr:`~pyfmodex.enums.DSP_PARAMETER_TYPE.INT`. :ivar DSP_PARAMETER_DESC_BOOL booldesc: Boolean format description used when type is :py:attr:`~pyfmodex.enums.DSP_PARAMETER_TYPE.BOOL`. :ivar DSP_PARAMETER_DESC_DATA datadesc: Data format description used when type is :py:attr:`~pyfmodex.enums.DSP_PARAMETER_TYPE.DATA`. """ _fields_ = [ ("floatdesc", DSP_PARAMETER_DESC_FLOAT), ("intdesc", DSP_PARAMETER_DESC_INT), ("booldesc", DSP_PARAMETER_DESC_BOOL), ("datadesc", DSP_PARAMETER_DESC_DATA), ] class DSP_PARAMETER_DESC(Structure): """Base Structure for DSP parameter descriptions. :ivar DSP_PARAMETER_TYPE type: Parameter type. :ivar bytes name: Parameter Name. :ivar bytes label: Unit type label. :ivar str description: Description of the parameter. :ivar DSP_PARAMETER_DESC_UNION desc_union: Format description. """ _fields_ = [ ("type", c_int), ("name", c_char * 16), ("label", c_char * 16), ("description", c_char_p), ("desc_union", DSP_PARAMETER_DESC_UNION), ] class DSP_DESCRIPTION(Structure): """DSP description. This description structure allows the plugin writer to define all functionality required for a user defined DSP effect. :ivar int pluginsdkversion: The plugin SDK version. :ivar str name: DSP name. :ivar str version: Plugin writer's version number. :ivar int numinputbuffers: Number of input buffers to process. Use 0 for DSPs that only generate sound and 1 for effects that process incoming sound. :ivar int numoutputbuffers: Number of audio output buffers. Only one output buffer is currently supported. :ivar DSP_CREATE_CALLBACK create: Create callback. This is called when DSP unit is created. Set callback invoked by :ivar DSP_RELEASE_CALLBACK release: Release callback. This is called just before the unit is freed so the user can do any cleanup needed for the unit. :ivar DSP_RESET_CALLBACK reset: Reset callback. This is called by the user to reset any history buffers that may need resetting for a filter, when it is to be used or re-used for the first time to its initial clean state. Use to avoid clicks or artifacts. :ivar DSP_READ_CALLBACK read: Read callback. Processing is done here. :ivar DSP_PROCESS_CALLBACK process: Process callback. Can be specified instead of the read callback if any channel format changes occur between input and output. This also replaces shouldiprocess and should return an error if the effect is to be bypassed. :ivar DSP_SETPOSITION_CALLBACK setposition: Set position callback. This is called if the unit wants to update its position info but not process data, or reset a cursor position internally if it is reading data from a certain source. :ivar int numparameters: Number of parameters used in this filter. The user finds this with :py:attr:`~pyfmodex.dsp.DSP.num_parameters`. :ivar list(str) paramdesc: Variable number of parameter structures. :ivar DSP_SETPARAM_FLOAT_CALLBACK setparameterfloat: Set callback invoked by :py:meth:`~pyfmodex.dsp.DSP.set_parameter_float`. :ivar DSP_SETPARAM_INT_CALLBACK setparameterint: Set callback invoked by by :py:meth:`~pyfmodex.dsp.DSP.set_parameter_int` :ivar DSP_SETPARAM_BOOL_CALLBACK setparameterbool: Set callback invoked by :py:meth:`~pyfmodex.dsp.DSP.set_parameter_bool`. :ivar DSP_SETPARAM_DATA_CALLBACK setparameterdata: Set callback invoked by :py:meth:`~pyfmodex.dsp.DSP.set_parameter_data`. :ivar DSP_GETPARAM_FLOAT_CALLBACK getparameterfloat: Set callback invoked by :py:meth:`~pyfmodex.dsp.DSP.get_parameter_float`. :ivar DSP_GETPARAM_INT_CALLBACK getparameterint: Set callback invoked by :py:meth:`~pyfmodex.dsp.DSP.get_parameter_int`. :ivar DSP_GETPARAM_BOOL_CALLBACK getparameterbool: Set callback invoked by :py:meth:`~pyfmodex.dsp.DSP.get_parameter_bool`. :ivar DSP_GETPARAM_DATA_CALLBACK getparameterdata: Set callback invoked by :py:meth:`~pyfmodex.dsp.DSP.get_parameter_data`. :ivar DSP_SHOULDIPROCESS_CALLBACK shouldiprocess: This is called before processing. You can detect if inputs are idle and return FMOD_OK to process, or any other error code to avoid processing the effect. Use a count down timer to allow effect tails to process before idling! :ivar userdata: User data. :ivar DSP_SYSTEM_REGISTER_CALLBACK sys_register: Register callback. This is called when DSP unit is loaded/registered. Useful for 'global'/per system object init for plugin. :ivar DSP_SYSTEM_DEREGISTER_CALLBACK sys_deregister: Deregister callback. This is called when DSP unit is unloaded/deregistered. Useful as 'global'/per system object shutdown for plugin. :ivar DSP_SYSTEM_MIX_CALLBACK sys_mix: System mix stage callback. This is called when the mixer starts to execute or is just finishing executing. Useful for 'global'/per system object once a mix update calls for a plugin. There are two different ways to change a parameter in this architecture: - One is to use :py:meth:`~pyfmodex.dsp.DSP.set_parameter_float`/ :py:meth:`~pyfmodex.dsp.DSP.set_parameter_int`/ :py:meth:`~pyfmodex.dsp.DSP.set_parameter_bool`/ :py:meth:`~pyfmodex.dsp.DSP.set_parameter_data`. This is platform independent and is dynamic, so new unknown plugins can have their parameters enumerated and used. - The other is to use :py:meth:`~pyfmodex.dsp.DSP.show_config_dialog`. This is platform specific and requires a GUI, and will display a dialog box to configure the plugin. """ _fields_ = [ ("pluginsdkversion", c_uint), ("name", c_char * 32), ("version", c_uint), ("numinputbuffers", c_int), ("numoutputbuffers", c_int), ("create", DSP_CREATE_CALLBACK), ("release", DSP_RELEASE_CALLBACK), ("reset", DSP_RESET_CALLBACK), ("read", DSP_READ_CALLBACK), ("process", DSP_PROCESS_CALLBACK), ("setposition", DSP_SETPOSITION_CALLBACK), ("numparameters", c_int), ("paramdesc", POINTER(POINTER(DSP_PARAMETER_DESC))), ("setparameterfloat", DSP_SETPARAM_FLOAT_CALLBACK), ("setparameterint", DSP_SETPARAM_INT_CALLBACK), ("setparameterbool", DSP_SETPARAM_BOOL_CALLBACK), ("setparameterdata", DSP_SETPARAM_DATA_CALLBACK), ("getparameterfloat", DSP_GETPARAM_FLOAT_CALLBACK), ("getparameterint", DSP_GETPARAM_INT_CALLBACK), ("getparameterbool", DSP_GETPARAM_BOOL_CALLBACK), ("getparameterdata", DSP_GETPARAM_DATA_CALLBACK), ("shouldiprocess", DSP_SHOULDIPROCESS_CALLBACK), ("userdata", c_void_p), ("sys_register", DSP_SYSTEM_REGISTER_CALLBACK), ("sys_deregister", DSP_SYSTEM_DEREGISTER_CALLBACK), ("sys_mix", DSP_SYSTEM_MIX_CALLBACK), ] class ERRORCALLBACK_INFO(Structure): """Information describing an error that has occurred. :ivar RESULT result: Error code result. :ivar ERRORCALLBACK_INSTANCETYPE instancetype: Type of instance the error occurred on. :ivar instance: Instance pointer. :ivar str functionname: Function that the error occurred on. :ivar str functionparams: Function parameters that the error ocurred on """ _fields_ = [ ("result", c_int), ("instancetype", c_int), ("instance", c_void_p), ("functionname", c_char_p), ("functionparams", c_char_p), ] class OUTPUT_DESCRIPTION(Structure): """Output description. This description structure allows the plugin writer to define all functionality required for a user defined output device. Pass this structure to :py:meth:`~pyfmodex.system.System.register_output` to create a new output type, or if defining a dynamically loadable plugin, return it in a function called FMODGetOutputDescription. FMOD's plugin loader will look for this function in a dynamic library. There are several methods for driving the FMOD mixer to service the audio hardware: - Polled: if the audio hardware must be polled regularly set 'method' to :py:attr:`~pyfmodex.enums.OUTPUT_METHOD.POLLING`, FMOD will create a mixer thread that calls back via :py:data:`~pyfmodex.callback_prototypes.OUTPUT_GETPOSITION_CALLBACK`. Once an entire block of samples have played FMOD will call :py:data:`~pyfmodex.callback_prototypes.OUTPUT_LOCK_CALLBACK` to allow you to provide a destination pointer to write the next mix. - Callback: if the audio hardware provides a callback where you must provide a buffer of samples then set 'method' to :py:attr:`~pyfmodex.enums.OUTPUT_METHOD.MIX_BUFFERED`, and directly call :py:data:`~pyfmodex.function_prototypes.OUTPUT_READFROMMIXER`. - Synchronization: if the audio hardware provides a synchronization primitive to wait on then set 'method' to :py:attr:`~pyfmodex.enums.OUTPUT_METHOD.MIX_DIRECT`, and give a :py:data:`~pyfmodex.callback_prototypes.OUTPUT_MIXER_CALLBACK`. pointer. FMOD will create a mixer thread and call you repeatedly once :py:data:`~pyfmodex.callback_prototypes.OUTPUT_START_CALLBACK` has finished, you must wait on your primitive in this callback and upon wake call :py:data:`~pyfmodex.function_prototypes.OUTPUT_READFROMMIXER`. - Non-realtime: if you are writing a file or driving a non-realtime output call :py:data:`~pyfmodex.function_prototypes.OUTPUT_READFROMMIXER` from :py:data:`~pyfmodex.callback_prototypes.OUTPUT_UPDATE_CALLBACK`. Callbacks marked with 'user thread' will be called in response to the user of the FMOD Core API, in the case of the Studio API, the user is the Studio Update thread. :ivar int apiversion: The output plugin API version this plugin is built for. Set to this to FMOD_OUTPUT_PLUGIN_VERSION. :ivar str name: Name of the output plugin, encoded as a UTF-8 string. :ivar int version: Version of the output plugin. :ivar OUTPUT_METHOD method: Method by which the mixer is executed and buffered. :ivar OUTPUT_GETNUMDRIVERS_CALLBACK getnumdrivers: User thread callback to provide the number of attached sound devices. Called from :py:attr:`~pyfmodex.system.System.num_drivers`. :ivar OUTPUT_GETDRIVERINFO_CALLBACK getdriverinfo: User thread callback to provide information about a particular sound device. Called from :py:meth:`~pyfmodex.system.System.get_driver_info`. :ivar OUTPUT_INIT_CALLBACK init: User thread callback to allocate resources and provide information about hardware capabilities. Called from :py:meth:`~pyfmodex.system.System.init`. :ivar OUTPUT_START_CALLBACK start: User thread callback just before mixing should begin, calls to :py:data:`pyfmodex.callback_prototypes.OUTPUT_GETPOSITION_CALLBACK` / :py:data:`pyfmodex.callback_prototypes.OUTPUT_LOCK_CALLBACK` / :py:data:`pyfmodex.callback_prototypes.OUTPUT_UNLOCK_CALLBACK` / :py:data:`pyfmodex.callback_prototypes.OUTPUT_MIXER_CALLBACK` will start, you may call :py:data:`pyfmodex.function_prototypes.OUTPUT_READFROMMIXER` after this point. Called from :py:meth:`~pyfmodex.system.System.init`. :ivar OUTPUT_STOP_CALLBACK stop: User thread callback just after mixing has finished, calls to :py:data:`pyfmodex.callback_prototypes.OUTPUT_GETPOSITION_CALLBACK` / :py:data:`pyfmodex.callback_prototypes.OUTPUT_LOCK_CALLBACK` / :py:data:`pyfmodex.callback_prototypes.OUTPUT_UNLOCK_CALLBACK` / :py:data:`pyfmodex.callback_prototypes.OUTPUT_MIXER_CALLBACK` will have stopped, you may not call :py:data:`pyfmodex.function_prototypes.OUTPUT_READFROMMIXER` after this point. Called from :py:meth:`~pyfmodex.system.System.init`. :ivar OUTPUT_CLOSE_CALLBACK close: User thread callback to clean up resources allocated during :py:data:`pyfmodex.callback_prototypes.OUTPUT_INIT_CALLBACK`. Called from :py:meth:`~pyfmodex.system.System.init`. and :py:meth:`~pyfmodex.system.System.close`. :ivar OUTPUT_UPDATE_CALLBACK update: User thread callback once per frame to update internal state. Called from :py:meth:`~pyfmodex.system.System.update`. :ivar OUTPUT_GETHANDLE_CALLBACK gethandle: User thread callback to provide a pointer to the internal device object used to share with other audio systems. Called from :py:meth:`~pyfmodex.system.System.output_handle`. :ivar OUTPUT_GETPOSITION_CALLBACK getposition: Mixer thread callback to provide the hardware playback position in the output ring buffer. Called before a mix. :ivar OUTPUT_LOCK_CALLBACK lock: Mixer thread callback to provide a pointer the mixer can write to for the next block of audio data. Called before a mix. :ivar OUTPUT_UNLOCK_CALLBACK unlock: Mixer thread callback to signify the mixer has finished writing to the pointer from :py:data:`pyfmodex.callback_prototypes.OUTPUT_LOCK_CALLBACK`. Called after a mix. :ivar OUTPUT_MIXER_CALLBACK mixer: Mixer thread callback called repeatedly to give a thread for waiting on an audio hardware synchronization primitive. Ensure you have a reasonable timeout (~200ms) on your synchronization primitive and allow this callback to return once per wakeup to avoid deadlocks. :ivar OUTPUT_OBJECT3DGETINFO_CALLBACK object3dgetinfo: Mixer thread callback to provide information about the capabilities of 3D object hardware. Called during a mix. :ivar OUTPUT_OBJECT3DALLOC_CALLBACK object3dalloc: Mixer thread callback to reserve a hardware resources for a single 3D object. Called during a mix. :ivar OUTPUT_OBJECT3DFREE_CALLBACK object3dfree: Mixer thread callback to release a hardware resource previously acquired with :py:data:`pyfmodex.callback_prototypes.OUTPUT_OBJECT3DALLOC_CALLBACK`. Called during a mix. :ivar OUTPUT_OBJECT3DUPDATE_CALLBACK object3dupdate: Mixer thread callback once for every acquired 3D object every mix to provide 3D information and buffered audio. Called during a mix. :ivar OUTPUT_OPENPORT_CALLBACK openport: Main thread callback to open an auxiliary output port on the device. :ivar OUTPUT_CLOSEPORT_CALLBACK closeport: Main thread callback to close an auxiliary output port on the device. :ivar OUTPUT_DEVICELISTCHANGED_CALLBACK devicelistchanged: Main thread callback to notify that a change to the device list may have occurred. """ _fields_ = [ ("apiversion", c_uint), ("name", c_char_p), ("version", c_uint), ("method", c_uint), ("getnumdrivers", OUTPUT_GETNUMDRIVERS_CALLBACK), ("getdriverinfo", OUTPUT_GETDRIVERINFO_CALLBACK), ("init", OUTPUT_INIT_CALLBACK), ("start", OUTPUT_START_CALLBACK), ("stop", OUTPUT_STOP_CALLBACK), ("close", OUTPUT_CLOSE_CALLBACK), ("update", OUTPUT_UPDATE_CALLBACK), ("gethandle", OUTPUT_GETHANDLE_CALLBACK), ("getposition", OUTPUT_GETPOSITION_CALLBACK), ("lock", OUTPUT_LOCK_CALLBACK), ("unlock", OUTPUT_UNLOCK_CALLBACK), ("mixer", OUTPUT_MIXER_CALLBACK), ("object3dgetinfo", OUTPUT_OBJECT3DGETINFO_CALLBACK), ("object3dalloc", OUTPUT_OBJECT3DALLOC_CALLBACK), ("object3dfree", OUTPUT_OBJECT3DFREE_CALLBACK), ("object3dupdate", OUTPUT_OBJECT3DUPDATE_CALLBACK), ("openport", OUTPUT_OPENPORT_CALLBACK), ("closeport", OUTPUT_CLOSEPORT_CALLBACK), ("devicelistchanged", OUTPUT_DEVICELISTCHANGED_CALLBACK), ] OUTPUT_OBJECT3DINFO._fields_ = [ ("buffer", POINTER(c_float)), ("bufferlength", c_uint), ("position", VECTOR), ("gain", c_float), ("spread", c_float), ("priority", c_float), ] OUTPUT_STATE._fields_ = [ ("plugindata", c_void_p), ("readfrommixer", OUTPUT_READFROMMIXER), ("alloc", OUTPUT_ALLOC), ("free", OUTPUT_FREE), ("log", OUTPUT_LOG), ("copyport", OUTPUT_COPYPORT), ("requestreset", OUTPUT_REQUESTRESET), ] class PLUGINLIST(Structure): """Used to support lists of plugins within the one dynamic library. This structure is returned from a plugin as a pointer to a list where the last entry has :py:attr:`~pyfmodex.enums.PLUGINTYPE.MAX` and a NULL description. :ivar PLUGINTYPE type: Plugin type. :ivar description: One of the plugin description structures (:py:class:`DSP_DESCRIPTION`, :py:class:`OUTPUT_DESCRIPTION`, :py:class:`CODEC_DESCRIPTION`) """ _fields_ = [("type", c_int), ("description", c_void_p)] class REVERB_PROPERTIES(Structure): """Structure defining a reverb environment. Note the default reverb properties are the same as the :py:attr:`~pyfmodex.reverb_presets.REVERB_PRESET.GENERIC` preset. :ivar float DecayTime: Reverberation decay time. :ivar float EarlyDelay: Initial reflection delay time. :ivar float LateDelay: Late reverberation delay time relative to initial reflection. :ivar float HFReference: Reference high frequency. :ivar float HFDecayRatio: High-frequency to mid-frequency decay time ratio. Value that controls the echo density in the late reverberation decay. :ivar float Density: Value that controls the modal density in the late reverberation decay. :ivar float LowShelfFrequency: Reference low frequency :ivar float LowShelfGain: Relative room effect level at low frequencies. :ivar float HighCut: Relative room effect level at high frequencies. :ivar float EarlyLateMix: Early reflections level relative to room effect. :ivar float WetLevel: Room effect level at mid frequencies. """ _fields_ = [ ("DecayTime", c_float), ("EarlyDelay", c_float), ("LateDelay", c_float), ("HFReference", c_float), ("HFDecayRatio", c_float), ("Diffusion", c_float), ("Density", c_float), ("LowShelfFrequency", c_float), ("LowShelfGain", c_float), ("HighCut", c_float), ("EarlyLateMix", c_float), ("WetLevel", c_float), ] class TAG(Structure): """Tag data / metadata description. :ivar TAGTYPE type: Tag type. :ivar TAGDATATYPE datatype: Tag data type. :ivar str name: Name. :ivar data: Tag data. :ivar int datalen: Size of data. :ivar bool updated: True if this tag has been updated since last being accessed with :py:meth:`~pyfmodex.sound.Sound.get_tag`. """ _fields_ = [ ("type", c_int), ("datatype", c_int), ("name", c_char_p), ("data", c_void_p), ("datalen", c_uint), ("updated", c_bool), ]