[FFmpeg-soc] [soc] libavsequencer [PATCH 05/08] Instrument handling public API header file.

[Vitor Sessak]

On 07/11/2010 10:07 PM, Sebastian Vater wrote:
> Updated patch for instrument.h.

> /*
>  * AVSequencer instrument management
>  * Copyright (c) 2010 Sebastian Vater <cdgs.basty at googlemail.com>
>  *
>  * This file is part of FFmpeg.
>  *
>  * FFmpeg 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.
>  *
>  * FFmpeg 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 FFmpeg; if not, write to the Free Software
>  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
>  */
>
> #ifndef AVSEQUENCER_INSTR_H
> #define AVSEQUENCER_INSTR_H
>
> #include "libavformat/avformat.h"
> #include "libavsequencer/sample.h"
>
> /**
>  * Envelope structure used by instruments to apply volume / panning
>  * or pitch manipulation according to an user defined waveform.
>  * New fields can be added to the end with minor version bumps.
>  * Removal, reordering and changes to existing fields require a major
>  * version bump.
>  */
> typedef struct AVSequencerEnvelope {

Why not just

typedef struct {

?

>     /** The actual node data of this envelope as signed 16-bit integer.

The comment is cryptic for someone who doesn't know what the node data 
of the envelope might be.

>        For a volume envelope, we have a default scale range of -32767
>        to +32767, for panning envelopes the scale range is between -8191
>        to +8191. For slide, vibrato, tremolo, pannolo (and their auto
>        versions), the scale range is between -256 to +256.  */
>     int16_t *data;
> #define AVSEQ_ENVELOPE_SCALE_MAX        0x7FFF
> #define AVSEQ_ENVELOPE_SCALE_INVALID    ((FF_AVSEQ_ENVELOPE_SCALE_MAX) + 1)
> #define AVSEQ_ENVELOPE_VOLUME_SCALE     0x7FFF
> #define AVSEQ_ENVELOPE_PANNING_SCALE    0x1FFF
> #define AVSEQ_ENVELOPE_SLIDE_SCALE      0x0100
> #define AVSEQ_ENVELOPE_VIBRATO_SCALE    0x0100
> #define AVSEQ_ENVELOPE_VIBRATO_SCALE    0x0100
>
>     /** The node points values or 0 if the envelope is empty.  */
>     uint16_t *node_points;
>
>     /** Number of dragable nodes of this envelope (defaults to 12).  */
>     uint16_t nodes;
> #define AVSEQ_ENVELOPE_NODES    12
>
>     /** Number of envelope points, i.e. node data values which
>        defaults to 64.  */
>     uint16_t points;
> #define AVSEQ_ENVELOPE_POINTS   64
>
>     /** Instrument envelope flags. Some sequencers feature
>        loop points of various kinds, which have to be taken
>        care specially in the internal playback engine.  */
>     uint16_t flags;
> #define AVSEQ_ENVELOPE_LOOP             0x0001 ///< Envelope uses loop nodes
> #define AVSEQ_ENVELOPE_SUSTAIN          0x0002 ///< Envelope uses sustain nodes
> #define AVSEQ_ENVELOPE_PINGPONG         0x0004 ///< Envelope loop is in ping pong mode
> #define AVSEQ_ENVELOPE_SUSTAIN_PINGPONG 0x0008 ///< Envelope sustain loop is in ping pong mode
>
>     /** Envelope tempo in ticks (defaults to 1, i.e. change envelope
>        at every frame / tick).  */
>     uint16_t tempo;
> #define AVSEQ_ENVELOPE_TEMPO    1
>
>     /** Envelope sustain loop start point.  */
>     uint16_t sustain_start;
>
>     /** Envelope sustain loop end point.  */
>     uint16_t sustain_end;

>     /** Envelope sustain loop repeat counter for loop range.  */
>     uint16_t sustain_count;
>
>     /** Envelope loop repeat start point.  */
>     uint16_t loop_start;
>
>     /** Envelope loop repeat end point.  */
>     uint16_t loop_end;
>
>     /** Envelope loop repeat counter for loop range.  */
>     uint16_t loop_count;
>
>     /** Randomized lowest value allowed.  */
>     int16_t value_min;
>
>     /** Randomized highest value allowed.  */
>     int16_t value_max;
>
>     /** Array of pointers containing every unknown data field where
>        the last element is indicated by a NULL pointer reference. The
>        first 64-bit of the unknown data contains an unique identifier
>        for this chunk and the second 64-bit data is actual unsigned
>        length of the following raw data. Some formats are chunk based
>        and can store information, which can't be handled by some
>        other, in case of a transition the unknown data is kept as is.
>        Some programs write editor settings for envelopes in those
>        chunks, which then won't get lost in that case.  */
>     uint8_t **unknown_data;
> } AVSequencerEnvelope;
>
> /**
>  * Keyboard definitions structure used by instruments to map
>  * note to samples. C-0 is first key. B-9 is 120th key.
>  * New fields can be added to the end with minor version bumps.
>  * Removal, reordering and changes to existing fields require a major
>  * version bump.
>  */
> typedef struct AVSequencerKeyboard {
>     struct AVSequencerKeyboardEntry {
>         /** Sample number for this keyboard note.  */
>         uint16_t sample;
>
>         /** Octave value for this keyboard note.  */
>         uint8_t octave;
>
>         /** Note value for this keyboard note.  */
>         uint8_t note;
>     } key[120];
> } AVSequencerKeyboard;
>
> /**
>  * Arpeggio data structure, This structure is actually for one tick
>  * and therefore actually pointed as an array with the amount of
>  * different ticks handled by the arpeggio control.
>  * New fields can be added to the end with minor version bumps.
>  * Removal, reordering and changes to existing fields require a major
>  * version bump.
>  */
> typedef struct AVSequencerArpeggioData {
>     /** Packed note or 0 if this is an arpeggio note.  */
>     uint8_t tone;
>
>     /** Transpose for this arpeggio tick.  */
>     int8_t transpose;
>
>     /** Instrument number to switch to or 0 for original instrument.  */
>     uint16_t instrument;
>
>     /** The four effect command bytes which are executed.  */
>     uint8_t command[4];
>
>     /** The four data word values of the four effect command bytes.  */
>     uint16_t data[4];
> } AVSequencerArpeggioData;
>
> /**
>  * Arpeggio control envelope used by all instrumental stuff.
>  * New fields can be added to the end with minor version bumps.
>  * Removal, reordering and changes to existing fields require a major
>  * version bump.
>  */
> typedef struct AVSequencerArpeggio {
>     /** AVSequencerArpeggioData pointer to arpeggio data structure.  */
>     AVSequencerArpeggioData *data;
>
>     /** Instrument arpeggio control flags. Some sequencers feature
>        customized arpeggio command control.which have to be taken
>        care specially in the internal playback engine.  */
>     uint16_t flags;
> #define AVSEQ_ARPEGGIO_FLAG_LOOP                0x0001   ///< Arpeggio control is looped
> #define AVSEQ_ARPEGGIO_FLAG_SUSTAIN             0x0002   ///< Arpeggio control has a sustain loop
> #define AVSEQ_ARPEGGIO_FLAG_PINGPONG            0x0004   ///< Arpeggio control will be looped in ping pong mpde
> #define AVSEQ_ARPEGGIO_FLAG_SUSTAIN_PINGPONG    0x0008   ///< Arpeggio control will have sustain loop ping pong mode enabled
>
>     /** Number of arpeggio ticks handled by this arpeggio control
>        (defaults to 3 points as in normal arpeggio command).  */
>     uint16_t entries;
> #define AVSEQ_ARPEGGIO_FLAG_ENTRIES 3
>
>     /** Sustain loop start tick of arpeggio control.  */
>     uint16_t sustain_start;
>
>     /** Sustain loop end tick of arpeggio control.  */
>     uint16_t sustain_end;
>
>     /** Sustain loop count number of how often to repeat loop
>        of arpeggio control.  */
>     uint16_t sustain_count;
>
>     /** Loop start tick of arpeggio control.  */
>     uint16_t loop_start;
>
>     /** Loop end tick of arpeggio control.  */
>     uint16_t loop_end;
>
>     /** Loop count number of how often to repeat loop of arpeggio
>        control.  */
>     uint16_t loop_count;

This look repeated frequently. Why not a struct for loops?

-Vitor