robot_decoder.h

/* ScummVM - Graphic Adventure Engine
 *
 * ScummVM is the legal property of its developers, whose names
 * are too numerous to list here. Please refer to the COPYRIGHT
 * file distributed with this source distribution.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
 
#ifndef SCI_VIDEO_DECODERS_ROBOT_H
#define SCI_VIDEO_DECODERS_ROBOT_H
 
#include "audio/audiostream.h"           // for AudioStream
#include "audio/rate.h"                  // for st_sample_t
#include "common/array.h"                // for Array
#include "common/mutex.h"                // for StackLock, Mutex
#include "common/rect.h"                 // for Point, Rect (ptr only)
#include "common/scummsys.h"             // for int16, int32, byte, uint16
#include "sci/engine/vm_types.h"         // for NULL_REG, reg_t
#include "sci/graphics/helpers.h"        // for GuiResourceId
#include "sci/graphics/screen_item32.h"  // for ScaleInfo, ScreenItem (ptr o...
 
namespace Common { class SeekableReadStreamEndian; }
namespace Sci {
class Plane;
class SegManager;
 
// There were 3 different Robot video versions, used in the following games:
// - v4: PQ:SWAT demo
// - v5: KQ7 DOS, Phantasmagoria, PQ:SWAT, Lighthouse
// - v6: RAMA
//
// Notes on Robot v5/v6 format:
//
// Robot is a packetized streaming AV format that encodes multiple bitmaps +
// positioning data, plus synchronised audio, for rendering in the SCI graphics
// system.
//
// Unlike traditional AV formats, Robot videos almost always require playback
// within the game engine because certain information (like the resolution of
// the Robot coordinates and the background for the video) is dependent on data
// that does not exist within the Robot file itself. In version 6, robots could
// also participate in palette remapping by drawing remap pixels, and the
// information for processing these pixels is also not stored within the Robot
// file.
//
// The Robot container consists of a file header, an optional primer audio
// section, an optional colour palette, a frame seek index, a set of cuepoints,
// and variable-sized packets of compressed video+audio data.
//
// Integers in Robot files are coded using native endianness (LSB for x86
// versions, MSB for 68k/PPC versions).
//
// Robot video coding is a relatively simple variable-length compression with no
// interframe compression. Each cel in a frame is constructed from multiple
// contiguous data blocks, each of which can be independently compressed with
// LZS or left uncompressed. An entire cel can also be line decimated, where
// lines are deleted from the source bitmap at compression time and are
// reconstructed by decompression using line interpolation. Each cel also
// includes coordinates where it should be placed within the video frame,
// relative to the top-left corner of the frame.
//
// Audio coding is fixed-length, and all audio blocks except for the primer
// audio are the same size. Audio is encoded with Sierra SOL DPCM16 compression,
// and is split into two channels ('even' and 'odd'), each at a 11025Hz sample
// rate. The original signal is restored by interleaving samples from the two
// channels together. Channel packets are 'even' if they have an ''absolute
// position of audio'' that is evenly divisible by 2; otherwise, they are 'odd'.
// Because the channels use DPCM compression, there is an 8-byte runway at the
// start of every audio block that is never written to the output stream, which
// is used to move the signal to the correct location by the 9th sample.
//
// File header (v5/v6):
//
//  byte | description
//     0 | signature 0x16
//     1 | unused
//   2-5 | signature 'SOL\0'
//   6-7 | version (4, 5, and 6 are the only known versions)
//   8-9 | size of audio blocks
// 10-11 | primer is compressed flag
// 12-13 | unused
// 14-15 | total number of video frames
// 16-17 | embedded palette size, in bytes
// 18-19 | primer reserved size
// 20-21 | coordinate X-resolution (if 0, uses game coordinates)
// 22-23 | coordinate Y-resolution (if 0, uses game coordinates)
//    24 | if non-zero, Robot includes a palette
//    25 | if non-zero, Robot includes audio
// 26-27 | unused
// 28-29 | the frame rate, in frames per second
// 30-31 | coordinate conversion flag; if true, screen item coordinates
//       | from the robot should be used as-is with NO conversion when
//       | explicitly displaying a specific frame
// 32-33 | the maximum number of packets that can be skipped without causing
//       | audio drop-out
// 34-35 | the maximum possible number of cels that will be displayed in any
//       | frame of the robot
// 36-39 | the maximum possible size, in bytes, of the first fixed cel
// 40-43 | the maximum possible size, in bytes, of the second fixed cel
// 44-47 | the maximum possible size, in bytes, of the third fixed cel
// 48-51 | the maximum possible size, in bytes, of the fourth fixed cel
// 52-59 | unused
//
// If the ''file includes audio'' flag is false, seek ''primer reserved size''
// bytes from the end of the file header to get past a padding zone.
//
// If the ''file includes audio'' flag is true, and the ''primer reserved size''
// is not zero, the data immediately after the file header consists of an audio
// primer header plus compressed audio data:
//
// Audio primer header:
//
//  byte | description
//   0-3 | the size, in bytes, of the entire primer audio section
//   4-5 | the compression format of the primer audio (must be zero)
//   6-9 | the size, in bytes, of the "even" primer
// 10-13 | the size, in bytes, of the "odd" primer
//
// If the combined sizes of the even and odd primers do not match the ''primer
// reserved size'', the next header block can be found ''primer reserved size''
// bytes from the *start* of the audio primer header.
//
// Otherwise, if the Robot has audio, and the ''primer reserved size'' is zero,
// and the ''primer is compressed flag'' is set, the "even" primer size is
// 19922, the "odd" primer size is 21024, and the "even" and "odd" buffers
// should be zero-filled.
//
// Any other combination of these flags is an error.
//
// If the Robot has a palette, the next ''palette size'' bytes should be read
// as a SCI HunkPalette. Otherwise, seek ''palette size'' bytes from the current
// position to get to the frame index.
//
// The next section of the Robot is the video frame size index. In version 5
// robots, read ''total number of frames'' 16-bit integers to get the size of
// the compressed video for each frame. For version 6 robots, use 32-bit
// integers.
//
// The next section of the Robot is the packet size index (combined compressed
// size of video + audio for each frame). In version 5 Robots, read ''total
// number of frames'' 16-bit integers. In version 6 robots, use 32-bit integers.
//
// The next section of the Robot is the cue times index. Read 256 32-bit
// integers, which represent the number of ticks from the start of playback that
// the given cue point falls on.
//
// The next section of the Robot is the cue values index. Read 256 16-bit
// integers, which represent the actual cue values that will be passed back to
// the game engine when a cue is requested.
//
// Finally, to get to the first frame packet, seek from the current position to
// the start of the next 2048-byte-aligned sector.
//
// Frame packet:
//
//  byte | description
//  0..n | video data (size is in the ''video frame size index'')
// n+1.. | optional audio data (size is ''size of audio blocks'')
//
// Video data:
//
//  byte | description
//   0-2 | number of cels in the frame (max 10)
//  3..n | cels
//
// Cel:
//
//  0-17 | cel header
// 18..n | data chunks
//
// Cel header:
//
//  byte | description
//     0 | unused
//     1 | vertical scale factor, in percent decimation (100 = no decimation,
//       | 50 = 50% of lines were removed)
//   2-3 | cel width
//   4-5 | cel height
//   6-9 | unused
// 10-11 | cel x-position, in Robot coordinates
// 12-13 | cel y-position, in Robot coordinates
// 14-15 | cel total data chunk size, in bytes
// 16-17 | number of data chunks
//
// Cel data chunk:
//
//   0-9 | cel data chunk header
// 10..n | cel data
//
// Cel data chunk header:
//
//  byte | description
//   0-3 | compressed size
//   4-7 | decompressed size
//   8-9 | compression type (0 = LZS, 2 = uncompressed)
//
// Random frame seeking can be done by calculating the address of the frame
// packet by adding up the ''packet size index'' entries up to the current
// frame. This will normally disable audio playback, as audio data in a packet
// does not correspond to the video in the same packet.
//
// Audio data is placed immediately after the end of the video data in a packet,
// and consists of an audio header plus compressed audio data:
//
// Audio data:
//
//  byte | description
//   0-7 | audio data header
//  8-15 | DPCM runway
// 16..n | compressed audio data
//
// Audio data header:
//
//  byte | description
//   0-3 | absolute position of audio in the audio stream
//   4-7 | the size of the audio block, excluding the header
//
// When a block of audio is processed, first check to ensure that the
// decompressed audio block's `position * 2 + length * 4` runs past the end of
// the last packet of the same evenness/oddness. Discard the audio block
// entirely if data has already been written past the end of this block for this
// channel, or if the read head has already read past the end of this audio
// block.
//
// If the block is not discarded, apply DPCM decompression to the entire block,
// starting from beginning of the DPCM runway, using an initial sample value of
// 0. Then, copy every sample from the decompressed source outside of the DPCM
// runway into every *other* sample of the final audio buffer (1 -> 2, 2 -> 4,
// 3 -> 6, etc.).
//
// Finally, for any skipped samples where the opposing (even/odd) channel did
// not yet write, interpolate the skipped areas by adding together the
// neighbouring samples from this audio block and dividing by two. (This allows
// the audio quality to degrade to 11kHz in case it takes too long to decode all
// the frames in the stream). Interpolated samples must not be written on top of
// true data from the opposing channel. Audio from later packets must also not
// be written on top of data in the same channel that was already written by an
// earlier packet, in particular because the first 8 bytes of the next packet
// are garbage data used to move the waveform to the correct position (due to
// the use of DPCM compression).
 
#pragma mark -
#pragma mark RobotAudioStream
 
class RobotAudioStream : public Audio::AudioStream {
public:
    enum {
        kRobotSampleRate = 22050,
 
        kEOSExpansion    = 2
    };
 
    struct StreamState {
        int bytesPlaying;
 
        uint16 rate;
 
        uint8 bits;
    };
 
    struct RobotAudioPacket {
        byte *data;
 
        int dataSize;
 
        int position;
 
        RobotAudioPacket(byte *data_, const int dataSize_, const int position_) :
            data(data_), dataSize(dataSize_), position(position_) {}
    };
 
    RobotAudioStream(const int32 bufferSize);
    ~RobotAudioStream() override;
 
    bool addPacket(const RobotAudioPacket &packet);
 
    void finish();
 
    StreamState getStatus() const;
 
private:
    Common::Mutex _mutex;
 
    byte *_loopBuffer;
 
    int32 _loopBufferSize;
 
    int32 _readHead;
 
    int32 _readHeadAbs;
 
    int32 _maxWriteAbs;
 
    int32 _writeHeadAbs;
 
    int32 _jointMin[2];
 
    bool _waiting;
 
    bool _finished;
 
    int32 _firstPacketPosition;
 
    byte *_decompressionBuffer;
 
    int32 _decompressionBufferSize;
 
    int32 _decompressionBufferPosition;
 
    void fillRobotBuffer(const RobotAudioPacket &packet, const int8 bufferIndex);
 
    void interpolateMissingSamples(const int32 numSamples);
 
#pragma mark -
#pragma mark RobotAudioStream - AudioStream implementation
public:
    int readBuffer(int16 *outBuffer, int numSamples) override;
    bool isStereo() const override { return false; };
    int getRate() const override { return 22050; };
    bool endOfData() const override {
        Common::StackLock lock(_mutex);
        return _readHeadAbs >= _writeHeadAbs;
    };
    bool endOfStream() const override {
        Common::StackLock lock(_mutex);
        return _finished && endOfData();
    }
};
 
#pragma mark -
#pragma mark RobotDecoder
 
class RobotDecoder {
public:
    RobotDecoder(SegManager *segMan);
    ~RobotDecoder();
 
    GuiResourceId getResourceId() const {
        return _robotId;
    }
 
private:
    SegManager *_segMan;
 
    GuiResourceId _robotId;
 
#pragma mark Constants
public:
    enum RobotStatus {
        kRobotStatusUninitialized = 0,
        kRobotStatusPlaying       = 1,
        kRobotStatusEnd           = 2,
        kRobotStatusPaused        = 3
    };
 
    enum {
        // Special high value used to represent parameters that should be left
        // unchanged when calling `showFrame`
        kUnspecified = 50000
    };
 
private:
    enum {
        kScreenItemListSize    = 10,
 
        kAudioListSize         = 10,
 
        kDelayListSize         = 10,
 
        kCueListSize           = 256,
 
        kFixedCelListSize      = 4,
 
        kRawPaletteSize        = 1200,
 
        kRobotFrameSize        = 2048,
 
        kRobotZeroCompressSize = 2048,
 
        kAudioBlockHeaderSize  = 8,
 
        kCelHeaderSize         = 22,
 
        kMaxFrameRateDrift     = 1
    };
 
    uint16 _version;
 
#pragma mark -
#pragma mark Initialisation
private:
    void initStream(const GuiResourceId robotId);
 
    void initPlayback();
 
    void initAudio();
 
    void initVideo(const int16 x, const int16 y, const int16 scale, const reg_t plane, const bool hasPalette, const uint16 paletteSize);
 
    void initRecordAndCuePositions();
 
#pragma mark -
#pragma mark Playback
public:
    void open(const GuiResourceId robotId, const reg_t plane, const int16 priority, const int16 x, const int16 y, const int16 scale);
 
    void close();
 
    void pause();
 
    void resume();
 
    void showFrame(const uint16 frameNo, const uint16 newX, const uint16 newY, const uint16 newPriority);
 
    int16 getCue() const;
 
    int16 getFrameNo() const;
 
    RobotStatus getStatus() const;
 
private:
    Common::SeekableReadStreamEndian *_stream;
 
    RobotStatus _status;
 
    typedef Common::Array<int> PositionList;
 
    PositionList _recordPositions;
 
    int32 _fileOffset;
 
    mutable int32 _cueTimes[kCueListSize];
 
    int32 _masterCueTimes[kCueListSize];
 
    int32 _cueValues[kCueListSize];
 
    int16 _frameRate;
 
    int16 _normalFrameRate;
 
    int16 _minFrameRate;
 
    int16 _maxFrameRate;
 
    int16 _maxSkippablePackets;
 
    int _currentFrameNo;
 
    int _previousFrameNo;
 
    int32 _startTime;
 
    int32 _startFrameNo;
 
    int32 _startingFrameNo;
 
    bool seekToFrame(const int frameNo);
 
    void setRobotTime(const int frameNo);
 
#pragma mark -
#pragma mark Timing
private:
    class DelayTime {
    public:
        DelayTime(RobotDecoder *decoder);
 
        void startTiming();
 
        void endTiming();
 
        bool timingInProgress() const;
 
        int predictedTicks() const;
 
    private:
        RobotDecoder *_decoder;
 
        uint32 _startTime;
 
        int _delays[kDelayListSize];
 
        uint _timestamps[kDelayListSize];
 
        uint _oldestTimestamp;
 
        uint _newestTimestamp;
 
        void sortList();
    };
 
    uint16 calculateNextFrameNo(const uint32 extraTicks = 0) const;
 
    uint32 ticksToFrames(const uint32 ticks) const;
 
    uint32 getTickCount() const;
 
    DelayTime _delayTime;
 
#pragma mark -
#pragma mark Audio
private:
    enum {
        kAudioSyncCheckInterval = 5 * 60 /* 5 seconds */
    };
 
    enum RobotAudioStatus {
        kRobotAudioReady    = 1,
        kRobotAudioStopped  = 2,
        kRobotAudioPlaying  = 3,
        kRobotAudioPaused   = 4,
        kRobotAudioStopping = 5
    };
 
#pragma mark -
#pragma mark Audio - AudioList
private:
    class AudioList {
    public:
        AudioList();
 
        void startAudioNow();
 
        void stopAudio();
 
        void stopAudioNow();
 
        void submitDriverMax();
 
        void addBlock(const int position, const int size, const byte *buffer);
 
        void reset();
 
        void prepareForPrimer();
 
        void setAudioOffset(const int offset);
 
#pragma mark -
#pragma mark Audio - AudioList - AudioBlock
 
    private:
        class AudioBlock {
        public:
            AudioBlock(const int position, const int size, const byte *const data);
            ~AudioBlock();
 
            bool submit(const int startOffset);
 
        private:
            int _position;
 
            int _size;
 
            byte *_data;
        };
 
        AudioBlock *_blocks[kAudioListSize];
 
        uint8 _blocksSize;
 
        uint8 _oldestBlockIndex;
 
        uint8 _newestBlockIndex;
 
        int _startOffset;
 
        RobotAudioStatus _status;
 
        void freeAudioBlocks();
    };
 
    bool _hasAudio;
 
    AudioList _audioList;
 
    uint16 _audioBlockSize;
 
    int16 _expectedAudioBlockSize;
 
    int16 _audioRecordInterval;
 
    uint16 _primerZeroCompressFlag;
 
    uint16 _primerReservedSize;
 
    int32 _totalPrimerSize;
 
    int32 _primerPosition;
 
    int32 _evenPrimerSize;
 
    int32 _oddPrimerSize;
 
    int32 _firstAudioRecordPosition;
 
    byte *_audioBuffer;
 
    uint32 _checkAudioSyncTime;
 
    bool primeAudio(const uint32 startTick);
 
    bool readPrimerData(byte *outEvenBuffer, byte *outOddBuffer);
 
    bool readAudioDataFromRecord(const int frameNo, byte *outBuffer, int &outAudioPosition, int &outAudioSize);
 
    bool readPartialAudioRecordAndSubmit(const int startFrame, const int startPosition);
 
#pragma mark -
#pragma mark Rendering
public:
    const reg_t getPlaneId() const {
        return _planeId;
    }
 
    Common::Point getPosition() const {
        return _position;
    }
 
    int16 getScale() const {
        return _scaleInfo.x;
    }
 
    uint16 getFrameSize(Common::Rect &outRect) const;
 
    void doRobot();
 
    void frameAlmostVisible();
 
    void frameNowVisible();
 
    void expandCel(byte *target, const byte* source, const int16 celWidth, const int16 celHeight) const;
 
    int16 getPriority() const;
 
    void setPriority(const int16 newPriority);
 
private:
    enum CompressionType {
        kCompressionLZS  = 0,
        kCompressionNone = 2
    };
 
    struct CelHandleInfo {
        enum CelHandleLifetime {
            kNoCel         = 0,
            kFrameLifetime = 1,
            kRobotLifetime = 2
        };
 
        reg_t bitmapId;
 
        CelHandleLifetime status;
 
        int area;
 
        CelHandleInfo() : bitmapId(NULL_REG), status(kNoCel), area(0) {}
    };
 
    typedef Common::Array<ScreenItem *> RobotScreenItemList;
    typedef Common::Array<CelHandleInfo> CelHandleList;
    typedef Common::Array<int> VideoSizeList;
    typedef Common::Array<uint> MaxCelAreaList;
    typedef Common::Array<reg_t> FixedCelsList;
    typedef Common::Array<Common::Point> CelPositionsList;
    typedef Common::Array<byte> ScratchMemory;
 
    void doVersion5(const bool shouldSubmitAudio = true);
 
    void createCels5(const byte *rawVideoData, const int16 numCels, const bool usePalette);
 
    uint32 createCel5(const byte *rawVideoData, const int16 screenItemIndex, const bool usePalette);
 
    void preallocateCelMemory(const byte *rawVideoData, const int16 numCels);
 
    DecompressorLZS _decompressor;
 
    reg_t _planeId;
 
    Common::Point _position;
 
    ScaleInfo _scaleInfo;
 
    int16 _xResolution, _yResolution;
 
    bool _isHiRes;
 
    int16 _maxCelsPerFrame;
 
    MaxCelAreaList _maxCelArea;
 
    uint8 *_rawPalette;
 
    VideoSizeList _videoSizes;
 
    FixedCelsList _fixedCels;
 
    CelHandleList _celHandles;
 
    ScratchMemory _celDecompressionBuffer;
 
    int _celDecompressionArea;
 
    bool _syncFrame;
 
    ScratchMemory _doVersion5Scratch;
 
    mutable int _cueForceShowFrame;
 
    Plane *_plane;
 
    RobotScreenItemList _screenItemList;
 
    Common::Array<int16> _screenItemX, _screenItemY;
 
    Common::Array<int16> _originalScreenItemX, _originalScreenItemY;
 
    uint16 _numFramesTotal;
 
    int16 _priority;
 
    uint8 _verticalScaleFactor;
};
 
} // end of namespace Sci
 
#endif // SCI_VIDEO_DECODERS_ROBOT_H