MPEGDecoder.h

Go to the documentation of this file.

// MPEGDecoder.h - interface of class MPEGDecoder
//
// Copyright (c) 2003, Roku, LLC.
//

#ifndef _ROKU_INCLUDE_DESCHUTES_LIBRARIES_HDMACHINEX225_MPEGDECODER_H
#define _ROKU_INCLUDE_DESCHUTES_LIBRARIES_HDMACHINEX225_MPEGDECODER_H

#include <cascade/CascadeTypedefs.h>
#include <cascade/graphics/CascadeRect.h>

// class MPEGDecoder settings #defines
#define DESCHUTES_MPEGDECODER_SETTINGS_SECTION              "deschutes-mpegdecoder"
#define DESCHUTES_MPEGDECODER_VARNAME_AC3PASSTHRU           "AC3PassThru"
#define DESCHUTES_MPEGDECODER_AC3PASSTHRU_DEFAULT           0

// class MPEGDecoder
class MPEGDecoder
{
public:
    // new EXPERIMENTAL types
    enum ClockSource { kClockSourceNone = 0, kExternalA, kExternalB, kAudioPLLA, kAudioPLLB, kVideoClock };
    enum ClockRecoveryMode { kRecoveryModeNone = 0, kOnce, kSoftware, kVideoHardware };
public:
    // new EXPERIMENTAL functions
    bool NewOpen(
        u32 nNumBuffers = 0,                            // use internal default
        u32 nBufferSizeInBytes = 0,                     // use internal default
        ClockSource videoClockSource = kVideoClock,
        ClockRecoveryMode videoClockRecoveryMode = kOnce,
        ClockSource audioClockSource = kAudioPLLA,
        ClockRecoveryMode audioClockRecoveryMode = kOnce,
        bool bEnableFeedThrottling = true,
        bool bAttachAudioClockToVideoClock = true,
        bool bSynchronizeVideo = true,      
        bool bSynchronizeAudio = false,
        u32 nAudioSyncThreshold = 50 * 90);             // 50 ms (in units of 90 kHz)
    
    // notes on nAudioSyncThreshold:
    //   if bSynchronizeAudio is true, then audio will be presented when |PTS-STC| < nAudioSyncThreshold

public: 
    MPEGDecoder();
    virtual ~MPEGDecoder();

public:
    bool GetBufferRequirements(u32 & nAlignmentToSet, u32 & nSizeMultipleToSet, u32 & nMaxBuffersToSet);
    bool Open(u32 nNumBuffers, u32 nBufferSizeInBytes);
        // video player is opened with the number and size of requested buffers
        // if either parameter is 0, the default num buffers and buffer size will be selected
        bool Close();
        // close the video player as soon as you are done with it so it can be used 
        // by other clients.
        bool IsOpen();
        // returns true if video player is open
    
    virtual u32 OnFillBuffer(u8 * pBuffer, u32 nBuffSize) = 0;
        // OnFillBuffer gets called whenever a buffer needs filling
        // Clients should fill the buffer with nBuffSize bytes and then
        // return the number of actual bytes filled.
        // If the returned number of actual bytes is less than nBuffSize,
        // then the buffer will be null-padded.

    virtual bool OnDecoderError() = 0;
        // OnDecoderError() gets called whenever the decoder encounters
        // an error while it is running.  These errors are usually hardware
        // errors.  Clients should return true to have the decoder remain streaming
        // or false to have the decoder enter the paused streaming state.

    bool SelectPIDs(bool bProgramStream, u32 nPCRPID, u32 nVideoPID, u32 nAudioPID, u32 nAudioSSID, bool bAC3Audio);
        // call SelectPIDs before or during streaming to select the pids that will
        // play back.  If any of the parameters are changed from their current settings,
        // any data in the pipeline will be streamed through before the change takes effect.
        // If any PID passed in is zero, that is interpreted as meaning don't play that stream type.
        // e.g. if nAudioPID is zero then audio will not be played back.
        // if bProgramStream is true then nPCRPID, nVideoPID, and nAudioPID will be interpreted
        // as stream id's, not PIDS.  If bProgramStream and bAC3Audio are true and nAudioSSID is non-zero,
        // then the substream identified by nAudioSSID will be used.

    bool SetOutputAndScaleRects(const CascadeRect & outputRect, const CascadeRect & scaleRect);
        // SetOutputAndScaleRects() should be called after every Open() to set the proper
        // output resolution and scale rects.  (Use the ones gotten from CascadeScreen).

    bool PauseStreaming();
        // PauseStreaming() pauses streaming.  PauseStreaming takes effect immediately and returns
        // true with no effect if streaming is already paused.
    bool ResumeStreaming();
        // ResumeStreaming() starts or resumes streaming.  Your OnFillBuffer member function will
        // get called back in the context of a streamer thread immediately after calling
        // ResumeStreaming() the first time.
        // If ResumeStreaming is called while streaming is already running, it returns true
        // with no effect.
    bool FlushStream(bool bDecode = true);
        // immediately flushes all pending buffers optionally running them
        // through the decoder.  Streaming will always be paused after FlushStream()
        // is called.
        // NOTE: FlushStream is currently not implemented; need to rethink trick modes
        // for un-trick decoder.
        
        // NOTE: returning short from OnFillBuffer no longer pauses streaming.

        // RenderSingleFrames()
        //
        //  Open();
        //  ResumeStreaming();
        //  -- fill buffer with 1 frame, return with short size
        //  ResumeStreaming();
        //  -- fill buffer with 1 frame, return with short size
        //  ResumeStreaming();
        //  -- fill buffer with 1 frame, return with short size

        // JumpToPositionAndPause()
        //
        //  Open();
        //  ResumeStreaming();
        //  -- fill buffer with 1 frame from position, return with short size

        // JumpToPositionAndPlay()
        //
        //  Open();
        //  ResumeStreaming();
        //  -- fill buffer with frames starting at position

        // JumpToPositionAndPlayNFrames()
        //
        //  Open();
        //  ResumeStreaming();
        //  -- fill buffer with N frames starting at position
        //  -- return short size when done

        // Variable speed rewind
        //
        //  Open();
        //  JumpToPositionAndPlayNFrames();
        //  -- decrement position
        //  JumpToPositionAndPlayNFrames();
        //  -- decrement position...

        // Variable speed FF
        //
        //  Open();
        //  JumpToPositionAndPlayNFrames();
        //  -- increment position
        //  JumpToPositionAndPlayNFrames();
        //  -- increment position...

        // End one file, play another, no gap
        //
        //  Open();
        //  ResumeStreaming();
        //  -- fill buffers for first file, when first file read
        //  -- is over, continue with second file

        // Jump from the middle of one file to another, no gap
        //
        //  Open();
        //  ResumeStreaming();
        //  -- fill buffers, when transfer time comes

        // Abort playback of 1 file, play another, no gap
        //
        //  Open();
        //  ResumeStreaming();
        //  -- fill buffers for first file, when abort point reached:
        //  FlushStreaming(false);
        //  ResumeStreaming();
        //  -- fill with new file

private:
    void * m_pDecoderInternal;
};

#endif // #ifndef _ROKU_INCLUDE_DESCHUTES_LIBRARIES_HDMACHINEX225_MPEGDECODER_H

//  LOG
//  13-Oct-03   dwoodward   created
//  24-Oct-03   dwoodward   added SetOutputAndScaleRects()
//  14-Nov-03   dwoodward   replaced independent pid selection with unified SelectPIDs function.
//  15-Apr-04   dwoodward   added new EXPERIMENTAL functions
//  13-Aug-04   dwoodward   added nAudioSSID to SelectPIDs.
//  07-Sep-04   dwoodward   updated comments to reflect life

---