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(Audio::st_sample_t *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