← Back to branch summary

~ubuntu-branches/ubuntu/utopic/ardour3/utopic

« back to all changes in this revision

Viewing changes to libs/taglib/taglib/mpeg/id3v2/frames/relativevolumeframe.h

  • Committer: Package Import Robot
  • Author(s): Felipe Sateler
  • Date: 2013-09-21 19:05:02 UTC
  • Revision ID: package-import@ubuntu.com-20130921190502-8gsftrku6jnzhd7v
Tags: upstream-3.4~dfsg
Import upstream version 3.4~dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/taglib/taglib/mpeg/id3v2/frames/relativevolumeframe.h
 
1
/***************************************************************************
 
2
    copyright            : (C) 2002 - 2008 by Scott Wheeler
 
3
    email                : wheeler@kde.org
 
4
 ***************************************************************************/
 
5
 
 
6
/***************************************************************************
 
7
 *   This library is free software; you can redistribute it and/or modify  *
 
8
 *   it under the terms of the GNU Lesser General Public License version   *
 
9
 *   2.1 as published by the Free Software Foundation.                     *
 
10
 *                                                                         *
 
11
 *   This library is distributed in the hope that it will be useful, but   *
 
12
 *   WITHOUT ANY WARRANTY; without even the implied warranty of            *
 
13
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
 
14
 *   Lesser General Public License for more details.                       *
 
15
 *                                                                         *
 
16
 *   You should have received a copy of the GNU Lesser General Public      *
 
17
 *   License along with this library; if not, write to the Free Software   *
 
18
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
 
19
 *   USA                                                                   *
 
20
 *                                                                         *
 
21
 *   Alternatively, this file is available under the Mozilla Public        *
 
22
 *   License Version 1.1.  You may obtain a copy of the License at         *
 
23
 *   http://www.mozilla.org/MPL/                                           *
 
24
 ***************************************************************************/
 
25
 
 
26
#ifndef TAGLIB_RELATIVEVOLUMEFRAME_H
 
27
#define TAGLIB_RELATIVEVOLUMEFRAME_H
 
28
 
 
29
#include <tlist.h>
 
30
#include <id3v2frame.h>
 
31
#include "taglib_export.h"
 
32
 
 
33
namespace TagLib {
 
34
 
 
35
  namespace ID3v2 {
 
36
 
 
37
    //! An ID3v2 relative volume adjustment frame implementation
 
38
 
 
39
    /*!
 
40
     * This is an implementation of ID3v2 relative volume adjustment.  The
 
41
     * presence of this frame makes it possible to specify an increase in volume
 
42
     * for an audio file or specific audio tracks in that file.
 
43
     *
 
44
     * Multiple relative volume adjustment frames may be present in the tag
 
45
     * each with a unique identification and describing volume adjustment for
 
46
     * different channel types.
 
47
     */
 
48
 
 
49
    class TAGLIB_EXPORT RelativeVolumeFrame : public Frame
 
50
    {
 
51
      friend class FrameFactory;
 
52
 
 
53
    public:
 
54
 
 
55
      /*!
 
56
       * This indicates the type of volume adjustment that should be applied.
 
57
       */
 
58
      enum ChannelType {
 
59
        //! A type not enumerated below
 
60
        Other        = 0x00,
 
61
        //! The master volume for the track
 
62
        MasterVolume = 0x01,
 
63
        //! The front right audio channel
 
64
        FrontRight   = 0x02,
 
65
        //! The front left audio channel
 
66
        FrontLeft    = 0x03,
 
67
        //! The back right audio channel
 
68
        BackRight    = 0x04,
 
69
        //! The back left audio channel
 
70
        BackLeft     = 0x05,
 
71
        //! The front center audio channel
 
72
        FrontCentre  = 0x06,
 
73
        //! The back center audio channel
 
74
        BackCentre   = 0x07,
 
75
        //! The subwoofer audio channel
 
76
        Subwoofer    = 0x08
 
77
      };
 
78
 
 
79
      //! Struct that stores the relevant values for ID3v2 peak volume
 
80
 
 
81
      /*!
 
82
       * The peak volume is described as a series of bits that is padded to fill
 
83
       * a block of bytes.  These two values should always be updated in tandem.
 
84
       */
 
85
      struct PeakVolume
 
86
      {
 
87
        /*!
 
88
         * Constructs an empty peak volume description.
 
89
         */
 
90
        PeakVolume() : bitsRepresentingPeak(0) {}
 
91
        /*!
 
92
         * The number of bits (in the range of 0 to 255) used to describe the
 
93
         * peak volume.
 
94
         */
 
95
        unsigned char bitsRepresentingPeak;
 
96
        /*!
 
97
         * The array of bits (represented as a series of bytes) used to describe
 
98
         * the peak volume.
 
99
         */
 
100
        ByteVector peakVolume;
 
101
      };
 
102
 
 
103
      /*!
 
104
       * Constructs a RelativeVolumeFrame.  The relevant data should be set
 
105
       * manually.
 
106
       */
 
107
      RelativeVolumeFrame();
 
108
 
 
109
      /*!
 
110
       * Constructs a RelativeVolumeFrame based on the contents of \a data.
 
111
       */
 
112
      RelativeVolumeFrame(const ByteVector &data);
 
113
 
 
114
      /*!
 
115
       * Destroys the RelativeVolumeFrame instance.
 
116
       */
 
117
      virtual ~RelativeVolumeFrame();
 
118
 
 
119
      /*!
 
120
       * Returns the frame's identification.
 
121
       *
 
122
       * \see identification()
 
123
       */
 
124
      virtual String toString() const;
 
125
 
 
126
      /*!
 
127
       * Returns a list of channels with information currently in the frame.
 
128
       */
 
129
      List<ChannelType> channels() const;
 
130
 
 
131
      /*!
 
132
       * \deprecated Always returns master volume.
 
133
       */
 
134
      ChannelType channelType() const;
 
135
 
 
136
      /*!
 
137
       * \deprecated This method no longer has any effect.
 
138
       */
 
139
      void setChannelType(ChannelType t);
 
140
 
 
141
      /*
 
142
       * There was a terrible API goof here, and while this can't be changed to
 
143
       * the way it appears below for binary compaibility reasons, let's at
 
144
       * least pretend that it looks clean.
 
145
       */
 
146
 
 
147
#ifdef DOXYGEN
 
148
 
 
149
      /*!
 
150
       * Returns the relative volume adjustment "index".  As indicated by the
 
151
       * ID3v2 standard this is a 16-bit signed integer that reflects the
 
152
       * decibils of adjustment when divided by 512.
 
153
       *
 
154
       * This defaults to returning the value for the master volume channel if
 
155
       * available and returns 0 if the specified channel does not exist.
 
156
       *
 
157
       * \see setVolumeAdjustmentIndex()
 
158
       * \see volumeAjustment()
 
159
       */
 
160
      short volumeAdjustmentIndex(ChannelType type = MasterVolume) const;
 
161
 
 
162
      /*!
 
163
       * Set the volume adjustment to \a index.  As indicated by the ID3v2
 
164
       * standard this is a 16-bit signed integer that reflects the decibils of
 
165
       * adjustment when divided by 512.
 
166
       *
 
167
       * By default this sets the value for the master volume.
 
168
       *
 
169
       * \see volumeAdjustmentIndex()
 
170
       * \see setVolumeAjustment()
 
171
       */
 
172
      void setVolumeAdjustmentIndex(short index, ChannelType type = MasterVolume);
 
173
 
 
174
      /*!
 
175
       * Returns the relative volume adjustment in decibels.
 
176
       *
 
177
       * \note Because this is actually stored internally as an "index" to this
 
178
       * value the value returned by this method may not be identical to the
 
179
       * value set using setVolumeAdjustment().
 
180
       *
 
181
       * This defaults to returning the value for the master volume channel if
 
182
       * available and returns 0 if the specified channel does not exist.
 
183
       *
 
184
       * \see setVolumeAdjustment()
 
185
       * \see volumeAdjustmentIndex()
 
186
       */
 
187
      float volumeAdjustment(ChannelType type = MasterVolume) const;
 
188
 
 
189
      /*!
 
190
       * Set the relative volume adjustment in decibels to \a adjustment.
 
191
       *
 
192
       * By default this sets the value for the master volume.
 
193
       *
 
194
       * \note Because this is actually stored internally as an "index" to this
 
195
       * value the value set by this method may not be identical to the one
 
196
       * returned by volumeAdjustment().
 
197
       *
 
198
       * \see setVolumeAdjustment()
 
199
       * \see volumeAdjustmentIndex()
 
200
       */
 
201
      void setVolumeAdjustment(float adjustment, ChannelType type = MasterVolume);
 
202
 
 
203
      /*!
 
204
       * Returns the peak volume (represented as a length and a string of bits).
 
205
       *
 
206
       * This defaults to returning the value for the master volume channel if
 
207
       * available and returns 0 if the specified channel does not exist.
 
208
       *
 
209
       * \see setPeakVolume()
 
210
       */
 
211
      PeakVolume peakVolume(ChannelType type = MasterVolume) const;
 
212
 
 
213
      /*!
 
214
       * Sets the peak volume to \a peak.
 
215
       *
 
216
       * By default this sets the value for the master volume.
 
217
       *
 
218
       * \see peakVolume()
 
219
       */
 
220
      void setPeakVolume(const PeakVolume &peak, ChannelType type = MasterVolume);
 
221
 
 
222
#else
 
223
 
 
224
      // BIC: Combine each of the following pairs of functions (or maybe just
 
225
      // rework this junk altogether).
 
226
 
 
227
      short volumeAdjustmentIndex(ChannelType type) const;
 
228
      short volumeAdjustmentIndex() const;
 
229
 
 
230
      void setVolumeAdjustmentIndex(short index, ChannelType type);
 
231
      void setVolumeAdjustmentIndex(short index);
 
232
 
 
233
      float volumeAdjustment(ChannelType type) const;
 
234
      float volumeAdjustment() const;
 
235
 
 
236
      void setVolumeAdjustment(float adjustment, ChannelType type);
 
237
      void setVolumeAdjustment(float adjustment);
 
238
 
 
239
      PeakVolume peakVolume(ChannelType type) const;
 
240
      PeakVolume peakVolume() const;
 
241
 
 
242
      void setPeakVolume(const PeakVolume &peak, ChannelType type);
 
243
      void setPeakVolume(const PeakVolume &peak);
 
244
 
 
245
#endif
 
246
 
 
247
      /*!
 
248
       * Returns the identification for this frame.
 
249
       */
 
250
      String identification() const;
 
251
 
 
252
      /*!
 
253
       * Sets the identification of the frame to \a s. The string
 
254
       * is used to identify the situation and/or device where this
 
255
       * adjustment should apply.
 
256
       */
 
257
      void setIdentification(const String &s);
 
258
 
 
259
    protected:
 
260
      virtual void parseFields(const ByteVector &data);
 
261
      virtual ByteVector renderFields() const;
 
262
 
 
263
    private:
 
264
      RelativeVolumeFrame(const ByteVector &data, Header *h);
 
265
      RelativeVolumeFrame(const RelativeVolumeFrame &);
 
266
      RelativeVolumeFrame &operator=(const RelativeVolumeFrame &);
 
267
 
 
268
      class RelativeVolumeFramePrivate;
 
269
      RelativeVolumeFramePrivate *d;
 
270
    };
 
271
 
 
272
  }
 
273
}
 
274
#endif