Интерфейсы для аудио MPEG декодера mpgdec.dll¶
- Table of contents
- Интерфейсы для аудио MPEG декодера mpgdec.dll
Использование обычной или динамической библиотеки в проектах¶
- для компиляции используйте заголовок ‘mpgdec.h’
- заголовок компилируется по разному в зависимости от определенных макросов
USE_STATIC_LIB для компиляции статической версии библиотеки и/или кода, использующего её
DLL_BUILD для компиляции DLL версии библиотеки
nothing для кода, использующего DLL
- для статической линковки: mpgdec_static.lib (release); mpgdec_staticd.lib (debug).
- для линковки с DLL: mpgdec.lib (release) и mpgdecd.lib (debug);
- бинарники DLL: mpgdec.dll (release) и mpgdecd.dll (debug)
- все нужные файлы включая PDB присутствуют в MLIB
- код скомпилирован с многопоточной версией MSVC runtime library. в release версии оптимизация включена.
Использование типов и интерфесного класса¶
все объявления заголовка находятся внутри пространства имён MPEG.
p2impl-модель, интерфейсный класс ‘MPEG::Decoder’.
фабрика объектов - ‘MPEG::Decoder::Create()’.
1) создание/использование/уничтожение объектов декодера:
<code class="cpp">
MPEG::Decoder *decoderIface = MPEG::Decoder::Create( );
decoderIface->Decode( ... ... buffers etc ... ... );
decoderIface->Decode2( ... ... buffers etc ... ... );
decoderIface->SkipFrame( ... ... buffers etc ... ... );
decoderIface->ResetDecoder( true );
delete decoderIface; // not needed anymore
2) длина выходных буферов для ‘Decode(…)’ или ‘Decode2(…)’ задаётся
в сэмплах и может быть меньше размера MPEG фрейма в сэмплах
(1152/576/384 etcetera). Когда и если требуется, декодер может
использовать внутренние буфера и вернёт остаток сэмплов при
следующем вызове.
3) любой размер входных буферов приемлем. декодер накапливает байты
входного потока во внутренней очереди. декодер не будет генерировать
выходных сэмплов пока входных байт недостаточно для целого MPEG фрейма.
4) последовательные вызовы методов ‘Decode()’ или ‘Decode2()’ добавляют
буферы с байтами данных входного MPEG потока во внутреннюю очередь
декодера и генерируют выходной поток сэмплов. входные данные
рассматриваются как последовательность байт (образующих MPEG-фреймы).
метод ‘!ResetDecoder()’ может использоваться для очистки внутренних
буферов потоков и состояния декодера без его уничтожения/создания.
нельзя менять тип используемого интерфесного метода декодирования
(т.е. использовать разные методы ‘Decode()’ или ‘Decode2()’) без
промежуточного вызова ‘!ResetDecoder()’ для сброса его состояния.
То есть после создания сброса и до следующего сброса необходимо
вызывать один и тот же метод ‘Decode()’ или ‘Decode2()’.
5) Аргумент метода ‘!ResetDecoder()’ используется для различения полного
сброса (true) или перепозиционирования внутри входного MPEG-потока.
Рекомендуется без нужды не использовать ‘false’ : декодер может
обнаруживать ложные фреймы в потоке. Обычно ‘false’ используется только
при сканировании потока от начала для обнаружения первого фрейма.
6) существует две группы методов декодирования: ‘Decode(…)’ и ‘Decode2(…)’.
‘Decode(…)’ порождает стерео поток сэмплов из стерео MPEG потока, и
моно поток сэмплов из MPEG моно потока. ‘Decode2(…)’ всегда порождает
стерео поток выходных сэмплов.
Методы также слегка различаются в использовании аргументов следующим
образом:
- ‘Decode()’ помещает в выходной буфер сэмплы одного канала для
входных моно фреймов и чередующиеся сэмплы двух каналов для
входных стерео фреймов;
- выходной буфер для ‘Decode()’ должен иметь длину ‘outBufMaxSamples’
сэмплов (typeof(*outSampleBuf) - см объявление класса).
Возвращаемое значение ‘samplesDone’ равно полному числу сэмплов
записанных в выходной буфер по обоим каналам.
- ‘Decode2()’ всегда помещает в выходной буфер сэмплы двух каналов
для входных моно или стерео фреймов. В случае входного моно фрейма
выходные сэмплы дублируются в оба канала (попросту говоря
‘Decode2()’ генерирует стереопары одинаковых сэмплов для моно
фреймов);
- выходной буфер для ‘Decode2()’ должен иметь длину 2 * ‘outBufMaxSamples’
сэмплов. Возвращаемое значение ‘samplesDone’ равно числу "стереосэмплов"
записанных в выходной буфер (т.е. в выходной буфер будет записано всего
2 * ‘samplesDone’ одиночных сэмплов для обоих каналов).
7) смысл возвращаемых значений для ‘Decode(…)’ and ‘Decode2(…)’
- mpgOk декодер вернул некоторое количество сэмплов
(‘samplesDone’ не равно нулю);
- mpgComeAgain входной поток не содержит целого входного фрейма,
нет выходных сэмплов в буфере (‘samplesDone’ равно нулю).
если при вызове юыло передано некоторое количество
данных входного MPEG потока, они буферируются внутри
декодера и их не надо передавать в следующий раз снова;
- mpgError неверный входной поток или вызов метода декодирования
другого типа без промежуточного вызова ‘!ResetDecoder()’;
- mpgFatal фатальная невосстановимая ошибка (нет памяти и т.п.);
- mpgXingHeader выходной буфер содержит XING header (не аудиосэмплы!).
8) параметр ‘samplesClipped’ возвращает количество сэмплов которые были усечены
из-за переполнения при последнем вызове ‘Decode()’ для обеих каналов.
9) метод ‘!SkipFrame()’ пропускает в точности один входной MPEG фрейм. После вызова
его или любого метода ‘Decode()’ можно использовать метод ‘!GetInfo()’ чтобы
получить информацию из заголовка последнего декодированного MPEG фрейма.
11) информация о масштабировании аудио сэмплов:
- ‘Decode()’ and ‘Decode2()’ with sample type ‘short int’:
integer 16-bit signed samples in range –2!^15 …. +2!^15-1 (–32768 …. +32767).
- ‘Decode()’ and ‘Decode2()’ with sample type ‘double’:
same range as for ‘short int’ but floating point.
- ‘Decode()’ and ‘Decode2()’ with sample type ‘long int’:
signed 24-bit integer part + 8-bit fractional samples in range
–8388608 …. +8388607.99609375 (lower 8 bits are fractional part).
