Source: tdtfreader.h


Annotated List
Files
Globals
Hierarchy
Index
// ##########################################################################
// ####                                                                  ####
// ####                    Master Thesis Implementation                  ####
// ####  Management of Layered Variable Bitrate Multimedia Streams over  ####
// ####                  DiffServ with A Priori Knowledge                ####
// ####                                                                  ####
// #### ================================================================ ####
// ####                                                                  ####
// ####                                                                  ####
// #### TDTF Reader                                                      ####
// ####                                                                  ####
// #### Version 1.00  --  October 10, 2000                               ####
// ####                                                                  ####
// #### Copyright (C) 2000 Thomas Dreibholz                              ####
// #### University of Bonn, Department of Computer Science IV            ####
// #### EMail: Dreibholz@bigfoot.com                                     ####
// #### WWW:   http://www.bigfoot.com/~dreibholz/diplom/index.html       ####
// ####                                                                  ####
// ##########################################################################


#ifndef TDTF_READER
#define TDTF_READER


#include "system.h"
#include "tdtf.h"


namespace Coral {


/**
  * This class is a reader for a TDTF trace file. The file will be mapped
  * to memory using mmap() to provide easy access to trace and interval data.
  *
  * @short   Trace Reader
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
class TDTFReader
{
   // ====== Constructor/Destructor =========================================
   public:
   /**
     * Constructor.
     */
   TDTFReader();

   /**
     * Destructor.
     */
   virtual ~TDTFReader();


   // ====== Open/close TDTF trace file =====================================
   /**
     * Open TDTF trace file.
     *
     * @param name Name of TDTF trace file to open.
     * @param writable true, to open file in read/write mode; false otherwise.
     * @return true, if open operation has been successful; false otherwise.
     */
   virtual bool open(const char* name, const bool readWrite = false);

   /**
     * Close TDTF trace file.
     */
   virtual void close();

   /**
     * Check, if TDTF file has got resource/utilization lists.
     *
     * @return true, if lists are included; false otherwise.
     */
   inline bool hasResourceUtilizationLists() const;


   // ====== Frame rate methods =============================================
   /**
     * Check, if given frame rate is a valid value.
     *
     * @param frameRate Frame rate to be checked.
     * @return true, if given rate is valid; false otherwise.
     */
   bool isValidFrameRate(const double frameRate) const;

   /**
     * Get nearest lower valid frame rate for given frame rate.
     *
     * @param rate Frame rate.
     * @return Valid frame rate nearest to given rate.
     */
   double getNearestValidFrameRate(const double frameRate) const;

   /**
     * Get minimum frame rate.
     *
     * @return Minimum frame rate.
     */
   inline double getMinFrameRate() const;

   /**
     * Get maximum frame rate.
     *
     * @return Maximum frame rate.
     */
   inline double getMaxFrameRate() const;


   /**
     * Get next higher valid frame rate for given frame rate.
     *
     * @param frameRate Frame rate.
     * @return Next higher valid frame rate.
     */
   double getNextFrameRateForRate(const double frameRate) const;

   /**
     * Get next lower valid frame rate for given frame rate.
     *
     * @param frameRate Frame rate.
     * @return Next lower valid frame rate.
     */
   double getPrevFrameRateForRate(const double frameRate) const;


   // ====== Frame size methods =============================================
   /**
     * Get maximum number of bytes for given buffer delay (in frame rate units).
     *
     * @param rtpPosition RTP position within media.
     * @param layer Layer number.
     * @param frameRate Frame rate.
     * @param bufferDelay Buffer delay in frame rate units.
     * @return Maximum number of bytes.
     */
    cardinal getMaxByteCountForDelay(const card64   rtpPosition,
                                     const cardinal layer,
                                     const double   frameRate,
                                     const cardinal delay) const;

   /**
     * Get maximum number of frames for given buffer delay (in frame rate units).
     *
     * @param rtpPosition RTP position within media.
     * @param layer Layer number.
     * @param frameRate Frame rate.
     * @param bufferDelay Buffer delay in frame rate units.
     * @return Maximum number of frames.
     */
    cardinal getMaxFrameCountForDelay(const card64   rtpPosition,
                                      const cardinal layer,
                                      const double   frameRate,
                                      const cardinal delay) const;

   /**
     * Get payload frame size for given buffer delay (in frame rate units).
     *
     * @param rtpPosition RTP position within media.
     * @param layer Layer number.
     * @param frameRate Frame rate.
     * @param bufferDelay Buffer delay in frame rate units.
     * @return Payload frame size.
     */
   inline cardinal getPayloadFrameSizeForDelay(
                      const card64   rtpPosition,
                      const cardinal layer,
                      const double   frameRate,
                      const cardinal bufferDelay) const;

   /**
     * Get payload frame size for given position, layer and frame rate from trace.
     *
     * @param rtpPosition RTP position within media.
     * @param layer Layer number.
     * @param frameRate Frame rate.
     * @return Frame size.
     */
   cardinal getTraceFrameSize(const card64   rtpPosition,
                              const cardinal layer,
                              const double   frameRate) const;

   /**
     * Get frame ID for given position, layer and frame rate from trace.
     *
     * @param rtpPosition RTP position within media.
     * @param layer Layer number.
     * @param frameRate Frame rate.
     * @return Frame ID.
     */
   cardinal getTraceFrameID(const card64   rtpPosition,
                            const cardinal layer,
                            const double   frameRate) const;

   /**
     * Get layer scalability.
     *
     * @param rtpPosition RTP position within media.
     * @param layer Layer number.
     * @param frameRate Frame rate.
     * @return Layer scalability.
     */
   double getLayerScalability(const card64   rtpPosition,
                              const cardinal layer,
                              const double   frameRate) const;

   /**
     * Get layer flags.
     *
     * @param rtpPosition RTP position within media.
     * @param layer Layer number.
     * @param frameRate Frame rate.
     * @return Layer flags.
     */
   cardinal getLayerFlags(const card64   rtpPosition,
                          const cardinal layer,
                          const double   frameRate) const;

   /**
     * Get number of frames for given frame rate.
     *
     * @param frameRate Frame rate.
     * @return Number of frames.
     */
   cardinal getFrames(const double frameRate) const;

   /**
     * Get number of layers for given frame rate.
     *
     * @param frameRate Frame rate.
     * @return Number of layers.
     */
   cardinal getLayers(const double frameRate) const;


   // ====== Buffer delay methods ===========================================
   /**
     * Get maximum buffer delay for given position and frame rate.
     *
     * @param rtpPosition RTP position within media.
     * @param frameRate Frame rate.
     * @return Maximum buffer delay
     */
   cardinal getMaxBufferDelay(const card64 rtpPosition,
                              const double frameRate) const;


   // ====== TDTF trace file access =========================================
   /**
     * Check, if access to trace file at given position for given length
     * is within valid range.
     *
     * @param position File position.
     * @param length Access length.
     * @return true, is access is valid; false otherwise.
     */
   bool checkAccess(const cardinal position, const cardinal length) const;

   /**
     * Get TDTF prefix.
     *
     * @return Pointer to TDTF prefix.
     */
   const TDTFPrefix* TDTFReader::getTDTFPrefix() const;

   /**
     * Get TDTF suffix.
     *
     * @return Pointer to TDTF suffix.
     */
   const TDTFSuffix* TDTFReader::getTDTFSuffix() const;

   /**
     * Get entry for given frame rate from main index.
     *
     * @param frameRate Frame rate.
     * @return Pointer to entry.
     */
   const MainIndexEntry* getMainIndexEntry(const double frameRate) const;

   /**
     * Get trace header for given frame rate.
     *
     * @param frameRate Frame rate.
     * @return Pointer to trace header.
     */
   const TraceHeader* getTraceHeader(const double frameRate) const;

   /**
     * Get entry for given frame rate from Position/Length/Interval index.
     *
     * @param frameRate Frame rate.
     * @return Pointer to entry.
     */
   const PositionLengthIntervalIndexHeader* getIPLIHeader(
                                               const double frameRate) const;

   /**
     * Get interval header for given frame rate and position.
     *
     * @param position Position.
     * @param frameRate Frame rate.
     * @return Pointer to trace header.
     */
   const IntervalHeader* getIntervalHeader(const cardinal position,
                                           const double   frameRate) const;

   /**
     * Get layer header for given frame rate, position and layer.
     *
     * @param position Position.
     * @param layer Layer.
     * @param frameRate Frame rate.
     * @return Pointer to layer header.
     */
   const LayerHeader* getLayerHeader(const cardinal position,
                                     const cardinal layer,
                                     const double   frameRate) const;

   /**
     * Get empirical envelope for byterate or frame count for given
     * frame rate, layer and position.
     *
     * @param position Position.
     * @param layer Layer.
     * @param frameRate Frame rate.
     * @param frameCount true to get empirical envelope for frameCount; false for byterate.
     * @return Pointer to empirical envelope header.
     */
   const EmpiricalEnvelope* getEmpiricalEnvelope(const cardinal position,
                                                 const cardinal layer,
                                                 const double   frameRate,
                                                 const bool     frameCount = false) const;


   // ====== Resource/utilization methods ===================================
   /**
     * Get resource/utilization header for given position and frame rate.
     * @param position Position refering to *maximum* frame rate.
     * @param frameRate Frame rate.
     * @return ResourceUtilizationHeader.
     */
   const ResourceUtilizationHeader* getResourceUtilizationHeader(
                                       const cardinal position,
                                       const double   frameRate) const;

   /**
     * Get frame size utilization constants for given frame rate, layer and
     * position.
     *
     * @param position Position.
     * @param layer Layer.
     * @param frameRate Frame rate.
     * @return UtilizationHeader.
     */
   const UtilizationHeader* getFrameSizeUtilizationHeader(
                               const cardinal position,
                               const cardinal layer,
                               const double   frameRate) const;

   /**
     * Get frame rate utilization constants for given frame rate, layer and
     * position.
     *
     * @param position Position.
     * @param frameRate Frame rate.
     * @param a Reference to store constant A.
     * @param b Reference to store constant B.
     * @param c Reference to store constant C.
     * @return true on success; false otherwise.
     * @return UtilizationHeader.
     */
   const UtilizationHeader* getFrameRateUtilizationHeader(
                               const cardinal position,
                               const double   frameRate) const;


   // ====== RTP position conversion ============================================
   /**
     * Convert RTP position to frame position.
     *
     * @param frameRate Frame rate.
     * @param rtpPosition RTP position.
     * @return Frame position.
     */
   inline cardinal positionToFramePosition(const double frameRate,
                                           const card64 rtpPosition) const;

   /**
     * Convert frame position to RTP position.
     *
     * @param frameRate Frame rate.
     * @param framePosition Frame RTP position.
     * @return RTP position.
     */
   inline card64 framePositionToPosition(const double   frameRate,
                                         const cardinal framePosition) const;


   // ====== Printing methods ===============================================
   /**
     * Print empirical envelopes for all layers for byterate or
     * frame count for given frame rate and position.
     *
     * @param os Output stream.
     * @param frameRate Frame rate.
     * @param position Position.
     * @param compact true, to print *without* EE approximations; false otherwise.
     * @param frameCount true to get empirical envelope for frameCount; false for byterate.
     */
   void printEmpiricalEnvelope(ostream&       os,
                               const cardinal position,
                               const double   frameRate,
                               const bool     frameCount,
                               const bool     compact) const;

   /**
     * Print complete TDTF trace for given frame rate.
     *
     * @param os Output stream.
     * @param frameRate Frame rate.
     * @param printEE true, to print empirical envelope; false otherwise.
     * @param compactEE true, to print Empirical envelope *without* approximations; false otherwise.
     * @param printRUL true, to print resource/utilization list; false otherwise.
     * @param printUC true, to print utilization constants; false otherwise.
     */
   void print(ostream&     os,
              const double frameRate,
              const bool   printEE,
              const bool   compactEE,
              const bool   printRUL,
              const bool   printUC) const;


   // ====== Protected data =================================================
   public:
   int                                 InputFile;
   char*                               InputMemory;
   cardinal                            InputLength;


   protected:
   MainIndexHeader*                    MainIndex;
   cardinal                            MainIndexEntries;

   ResourceUtilizationListIndexHeader* RULIndex;
   cardinal                            RULIndexEntries;

   double                              MinFrameRate;
   double                              MaxFrameRate;
};


}


#include "tdtfreader.icc"


#endif

Generated by: viper@odin on Mon Oct 16 11:49:26 2000, using kdoc 2.0a36.