| 0,0 → 1,241 |
|---|
| /* |
| * Library to access OPL2/OPL3 hardware (YM3812 / YMF262) |
| * |
| * This file is part of the Mateusz' DOS Routines (MDR): http://mdr.osdn.io |
| * Published under the terms of the MIT License, as stated below. |
| * |
| * Copyright (C) 2015-2023 Mateusz Viste |
| * |
| * Permission is hereby granted, free of charge, to any person obtaining a copy |
| * of this software and associated documentation files (the "Software"), to |
| * deal in the Software without restriction, including without limitation the |
| * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or |
| * sell copies of the Software, and to permit persons to whom the Software is |
| * furnished to do so, subject to the following conditions: |
| * |
| * The above copyright notice and this permission notice shall be included in |
| * all copies or substantial portions of the Software. |
| * |
| * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
| * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS |
| * IN THE SOFTWARE. |
| */ |
| |
| #ifndef mdr_opl_h |
| #define mdr_opl_h |
| |
| struct mdr_opl_timbre { |
| unsigned char mod_ws, car_ws; /* waveform select (0-4), reg Exh */ |
| unsigned char mod_sr, car_sr; /* sustain/release, reg 8xh */ |
| unsigned char mod_ad, car_ad; /* attack/decay, reg 6xh */ |
| unsigned char mod_20, car_20; /* tremolo/vibrato/sustain..., reg 2xh */ |
| unsigned char mod_40, car_40; /* reg 4xh */ |
| unsigned char feedconn; |
| }; |
| |
| struct mdr_opl_timbretemplate { |
| struct { |
| unsigned char ws; /* waveform select 0..3 */ |
| unsigned char sustlev; /* sustain level 0..15 */ |
| unsigned char release; /* release level 0..15 */ |
| unsigned char attack; /* attack rate 0..15 */ |
| unsigned char decay; /* decay rate 0..15 */ |
| unsigned char tremolo; /* tremolo flag 0..1 */ |
| unsigned char vibrato; /* vibrato flag 0..1 */ |
| unsigned char sustain; /* sustain flag 0..1 */ |
| unsigned char ksr; /* KSR (envelope scaling) flag 0..1 */ |
| unsigned char mult; /* frequency multiplication factor 0..15 */ |
| unsigned char ksl; /* Key Scale Level 0..3 */ |
| unsigned char outlev; /* output level 0..63 */ |
| } carrier; |
| struct { |
| unsigned char ws; /* waveform select 0..3 */ |
| unsigned char sustlev; /* sustain level 0..15 */ |
| unsigned char release; /* release level 0..15 */ |
| unsigned char attack; /* attack rate 0..15 */ |
| unsigned char decay; /* decay rate 0..15 */ |
| unsigned char tremolo; /* tremolo flag 0..1 */ |
| unsigned char vibrato; /* vibrato flag 0..1 */ |
| unsigned char sustain; /* sustain flag 0..1 */ |
| unsigned char ksr; /* KSR (envelope scaling) flag 0..1 */ |
| unsigned char mult; /* frequency multiplication factor 0..15 */ |
| unsigned char ksl; /* Key Scale Level 0..3 */ |
| unsigned char outlev; /* output level 0..63 */ |
| } modultr; |
| unsigned char feedback;/* FeedBack Modulation Factor 0..7 */ |
| unsigned char conn; /* Synthesis type: 0=FM / 1=Additive */ |
| }; |
| |
| enum MDR_OPL_TIMER { |
| MDR_OPL_TIMER_80US = 2, |
| MDR_OPL_TIMER_320US = 3 |
| }; |
| |
| |
| /* frequency groups, to be used with mdr_opl_noteon() and mdr_opl_notebend(). |
| * There are 7 frequency groups to choose from. Each group supports a different |
| * span of frequencies. Higher groups have wider spans, but at the cost of larger |
| * difference between adjacent notes: |
| * |
| * Block Note 0 Note 1023 Step gap between adjacent notes |
| * FGROUP0 0.047 Hz 48.503 Hz 0.048 Hz |
| * FGROUP1 0.094 Hz 97.006 Hz 0.095 Hz |
| * FGROUP2 0.189 Hz 194.013 Hz 0.190 Hz |
| * FGROUP3 0.379 Hz 388.026 Hz 0.379 Hz |
| * FGROUP4 0.758 Hz 776.053 Hz 0.759 Hz |
| * FGROUP5 1.517 Hz 1552.107 Hz 1.517 Hz |
| * FGROUP6 3.034 Hz 3104.215 Hz 3.034 Hz |
| * FGROUP7 6.068 Hz 6208.431 Hz 6.069 Hz |
| * |
| * This shows that block 7 is capable of reaching the highest note (6.2kHz) but |
| * since there are 6 Hz between notes the accuracy suffers. Example: note A-4 |
| * is 440Hz but in this block, the two closest frequency numbers are 72 and 73, |
| * which create tones at 437Hz and 443Hz respectively, neither of which is |
| * particularly accurate. Blocks 3 and below are unable to reach as high as |
| * 440Hz, but block 4 can. With block 4, frequency numbers 579 and 580 produce |
| * 439.4 Hz and 440.2 Hz, considerably closer to the intended frequency. |
| * |
| * In other words, when calculating notes, the best accuracy is achieved by |
| * selecting the lowest possible block number that can reach the desired note |
| * frequency. |
| * |
| * More details: https://moddingwiki.shikadi.net/wiki/OPL_chip#A0-A8:_Frequency_Number |
| */ |
| |
| enum mdr_opl_fgroup_t { |
| MDR_OPL_FGROUP0 = 0, |
| MDR_OPL_FGROUP1 = 1 << 2, |
| MDR_OPL_FGROUP2 = 2 << 2, |
| MDR_OPL_FGROUP3 = 3 << 2, |
| MDR_OPL_FGROUP4 = 4 << 2, |
| MDR_OPL_FGROUP5 = 5 << 2, |
| MDR_OPL_FGROUP6 = 6 << 2, |
| MDR_OPL_FGROUP7 = 7 << 2 |
| }; |
| |
| /* Hardware detection and initialization. Must be called before any other |
| * OPL function. Returns 0 on success, non-zero otherwise. */ |
| int mdr_opl_init(void); |
| |
| /* close OPL device */ |
| void mdr_opl_close(void); |
| |
| /* turns off all notes */ |
| void mdr_opl_clear(void); |
| |
| /* loads an instrument described by properties in a timbre_t struct into |
| * the defined voice channel. The OPL2 chip supports up to 9 voice channels, |
| * from 0 to 8. The timbre struct can be freed right after this call. */ |
| void mdr_opl_loadinstrument(unsigned char voice, const struct mdr_opl_timbre *timbre); |
| |
| /* generate a timbre structure based on a timbre template. this is a |
| * convenience function meant to provide a human-compatible (more readable) |
| * way of generating a timbre struct. */ |
| int mdr_opl_timbre_gen(struct mdr_opl_timbre *timbre, const struct mdr_opl_timbretemplate *tpl); |
| |
| /* Triggers a note on selected voice channel. |
| * freqid is a value between 0 and 1023. The following formula can be used to |
| * determine the freq number for a given note frequency (Hz) and block: |
| * |
| * freqid = frequency * 2^(20 - block) / 49716 |
| * |
| * The note will be kept "pressed" until mdr_opl_noteoff() is called. */ |
| void mdr_opl_noteon(unsigned char voice, unsigned short freqid, enum mdr_opl_fgroup_t fgroup); |
| |
| /* changes the frequency of the note currently playing on voice channel, this |
| * can be used for pitch bending. */ |
| void mdr_opl_notebend(unsigned char voice, unsigned short freqid, enum mdr_opl_fgroup_t fgroup); |
| |
| /* releases a note on selected voice. */ |
| void mdr_opl_noteoff(unsigned char voice); |
| |
| /* adjusts volume of a voice. volume goes from 63 (mute) to 0 (loudest) */ |
| void mdr_opl_voicevolume(unsigned char voice, unsigned char volume); |
| |
| /* this is a LOW-LEVEL function that writes a data byte into the reg register |
| * of the OPL chip. Use this only if you know exactly what you are doing. */ |
| void mdr_opl_regwr(unsigned char reg, unsigned char data); |
| |
| |
| /***************************************************************************** |
| * IMF AUDIO FILES PLAYBACK * |
| * * |
| * It is possible to mix IMF playback calls with manual notes, but you must * |
| * take care to use only voices not used by your IMF audio. Typically games * |
| * tend to use the voice #0 for sound effects and voices #1 to #8 for music. * |
| * * |
| * The IMF API comes in two version: the normal one, or "imfeasy". The easy * |
| * version is easier to use, but requires to have the entire IMF audio file * |
| * loaded in memory, while the normal (non-easy) allows for more flexibility * |
| * in this regard, potentially allowing for playback of huge IMF files. * |
| *****************************************************************************/ |
| |
| /*** EASY INTERFACE ***/ |
| |
| /* playback initialization, easy interface. imf points to the start of the IMF |
| * file. The imf pointer must not be freed as long as playback is ongoing. |
| * imflength is the size (in bytes) of the IMF data. |
| * clock must be an incrementing value that wraps to 0 after 65535. The clock |
| * speed will control the playback's tempo. |
| * loopscount tells how many times the song will have to be looped (0 means |
| * "loop forever"). |
| * returns 0 on success, non-zero otherwise. */ |
| int mdr_opl_imfeasy_init(void *imf, unsigned short imflength, unsigned short clock, unsigned char loopscount); |
| |
| /* Playback of an IMF file preloaded via mdr_opl_imfeasy_init(). This function |
| * must be called repeatedly at a high frequency for best playback quality. |
| * Returns 0 on success, 1 if playback ended, -1 on error. */ |
| int mdr_opl_imfeasy_play(unsigned short clock); |
| |
| /*** ADVANCED INTERFACE ***/ |
| |
| /* playback initialization, this function must be called immediately before |
| * playback. imf points to the start of the IMF file and must contain at least |
| * the first 6 bytes of the audio file. |
| * clock must be an incrementing value that wraps to 0 after 65535. |
| * the clock speed will control the playback's tempo. |
| * returns the amount of consumed bytes (0, 4 or 6) */ |
| unsigned short mdr_opl_imf_init(void *imf, unsigned short clock); |
| |
| /* Playback, advanced version. Feeds the IMF playback routine with IMF data. |
| * Returns the amount of bytes that have been consumed, hence the next call |
| * should provide an imf pointer advanced by this many bytes (and imflen |
| * decreased accordingly). Such approach might not be the most intuitive, but |
| * it allows to load an imf song partially and provide only short chunks of |
| * data for playback instead of having to buffer the entire song in memory. |
| * For a simpler call that requires to buffer the entire IMF file in memory, |
| * see mdr_opl_imf_playeasy(). |
| * This function must be called repeatedly at a high frequency for best |
| * playback quality. */ |
| unsigned short mdr_opl_imf_play(void *imf, unsigned short imflen, unsigned short clock); |
| |
| |
| /***************************************************************************** |
| * OPL TIMER FUNCTIONS * |
| *****************************************************************************/ |
| |
| /* configures and starts a timer given type so it emits a tick every count |
| * periods. Two timer types are available: |
| * MDR_OPL_TIMER_80US - with a period of 80us |
| * MDR_OPL_TIMER_320US - with a period of 320us |
| * count may range from 0 to 255, but 0 means "256 periods". |
| * |
| * You may use only one timer at a time. |
| * |
| * EXAMPLE: setting up MDR_OPL_TIMER_80US with a count of 25 would make the |
| * timer tick every 2ms (25 * 80us). */ |
| void mdr_opl_timer_set(enum MDR_OPL_TIMER timertype, unsigned char count); |
| |
| /* returns 1 if timer tick occured, 0 otherwise. After a tick has been |
| * returned, this function will return 0 until next tick. |
| * |
| * it is important to note that there is no way to know whether one tick |
| * passed since last time, or more, so it is up to you to make sure you call |
| * this function fast enough. */ |
| unsigned char mdr_opl_timer_tick(void); |
| |
| #endif |