Source: tdtf.h


Annotated List
Files
Globals
Hierarchy
Index
// ##########################################################################
// ####                                                                  ####
// ####                    Master Thesis Implementation                  ####
// ####  Management of Layered Variable Bitrate Multimedia Streams over  ####
// ####                  DiffServ with A Priori Knowledge                ####
// ####                                                                  ####
// #### ================================================================ ####
// ####                                                                  ####
// ####                                                                  ####
// #### Thomas Dreibholz's Trace File (TDTF)                             ####
// ####                                                                  ####
// #### 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_H
#define TDTF_H


#include "system.h"


namespace Coral {


/**
  * This is an enumeration of predefined utility function types.
  */
enum UtilityFunctions
{
   /**
     * Linear: U(x) = x.
     * Parameters: none
     */
   UF_Linear = 0x0000,

   /**
     * Exponential #1 (from [LS98]): U(x) = 1 - exp(a*x + b).
     * a = (ln(-0.95 + 1) - b) / q95
     * b = (q95 * ln(-0.05 + 1) - q50 * ln(-0.95 + 1)) / (q95 - q50)
     *
     * Parameters:
     * q50 = Scale factor for 50% perceptual quality.
     * q95 = Scale facotr for 95% perceptual quality.
     */
   UF_Exponential1 = 0x0010,

   /**
     * Exponential #2 (from [Rog98]): U(x) = a*ln(b*x + c).
     * U(1) = 0, U(2) = 1.
     * This is equal to U(x) = a*ln(b*(x+1) + c) with U(0) = 0, U(1) = 1.
     * a = 1 / (p - 10)
     * b = exp(1/a) - 1
     * c = 2 - exp(1/a)
     *
     * Parameters:
     * p = Sensitivity
     */
   UF_Exponential2 = 0x0011,

   /**
     * Undefined.
     */
   UF_Undefined = 0xffff
};



/**
  * This is the TDTF prefix extension header.
  *
  * @short   TDTF Prefix Extension Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct TDTFPrefixExtensionHeader
{
   /**
     * ID of this extension (0x00000000, Length 0 for no more extensions).
     */
   char ExtID[4];

   /**
     * Length of the extension.
     */
   card32 ExtLength;
};



/**
  * This is a TDTF file's prefix.
  *
  * @short   TDTF Prefix.
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct TDTFPrefix
{
   /**
     * Current format version.
     */
   const static card32 CurrentVersion = 0x74660000;

   /**
     * Maximum title length.
     */
   const static cardinal MaxTitleLength = 64;

   /**
     * Maximum copyright length.
     */
   const static cardinal MaxCopyrightLength = 64;

   /**
     * Maximum comment length.
     */
   const static cardinal MaxCommentLength = 64;

   /**
     * Maximum URL length.
     */
   const static cardinal MaxURLLength = 128;


   /**
     * This is the TDTF ID: "TDTF".
     */
   char TDTF_ID[4];

   /**
     * Format version.
     */
   card32 Version;

   /**
     * Time stamp for start of trace creation.
     * It can be used to compute total creation time using TDTFSuffix's TraceTimeStamp.
     *
     * @see TDTFSuffix#TraceTimeStamp
     */
   card64 TraceTimeStamp;

   /**
     * Time stamp for start of utilization creation.
     * It can be used to compute total creation time using TDTFSuffix's
     * UtilizationTimeStamp.
     * If this time stamp is 0, a utilization has not been created yet
     * or is invalid (e.g. TUtilizer abortion or failure). Therefore, it can
     * also be used to check, if utilization information is valid.
     *
     * @see TDTFSuffix#UtilizationTimeStamp
     */
   card64 UtilizationTimeStamp;

   /**
     * Minimum interval length.
     */
   card64 MinIntervalLength;

   /**
     * Maximum interval length.
     */
   card64 MaxIntervalLength;

   /**
     * Title.
     */
   char Title[MaxTitleLength];

   /**
     * Copyright.
     */
   char Copyright[MaxCopyrightLength];

   /**
     * Comment.
     */
   char Comment[MaxCommentLength];

   /**
     * URL.
     */
   char URL[MaxURLLength];
};



/**
  * This is a TDTF file's suffix.
  *
  * @short   TDTF Suffix
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct TDTFSuffix
{
   /**
     * Time stamp for end of trace creation.
     * It can be used to compute total creation time using TDTFPrefix's TraceTimeStamp.
     *
     * @see TDTFPrefix#TraceTimeStamp
     */
   card64 TraceTimeStamp;

   /**
     * Time stamp for end of utilization creation.
     * It can be used to compute total creation time using TDTFPrefix's TraceTimeStamp.
     *
     * @see TDTFPrefix#UtilizationTimeStamp
     */
   card64 UtilizationTimeStamp;

   /**
     * Resource/utilization block start file position.
     */
   card32 ResourceUtilizationStart; 

   /**
     * Resource/utilization index;
     */
   card32 ResourceUtilizationIndex;

   /**
     * File position of the main index.
     */
   card32 MainIndex;

   /**
     * Trace block start file position.
     */
   card32 TraceStart;

   /**
     * This is the TDTF ID: "TDTF".
     */
   char TDTF_ID[4];
};



/**
  * This is a D-BIND entry of an empirical envelope.
  *
  * @short   Empirical Envelope Pair
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct EmpiricalEnvelopePair
{
   /**
     * Interval length.
     */
   card16 Interval;

   /**
     * Sum of bytes, frames, etc.: E(t).
     */
   card32 Sum;
};


/**
  * This is the header for an empirical envelope.
  *
  * @short   Empirical Envelope Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct EmpiricalEnvelope
{
   /**
     * Number of D-BIND entries.
     */
   card16 Pairs;

   /**
     * Array of D-BIND entries.
     */
   EmpiricalEnvelopePair Pair[0];


   // ====== Calculations ===================================================
   /**
     * Get empirical envelope size for given number of pairs.
     *
     * @param eePairs Pairs.
     * @return Size.
     */
   static inline cardinal getSize(const cardinal eePairs);

   /**
     * Get constraint for given buffer delay.
     *
     * @param bufferDelay Buffer delay.
     * @return Constraint.
     */
   cardinal getConstraint(const cardinal bufferDelay) const;
};



/**
  * This is an entry of a trace, it describes one frame.
  *
  * @short   Frame Description
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct FrameDescription
{
   /**
     * ID of the frame.
     */
   card32 ID;

   /**
     * Size of the frame.
     */
   card32 Size;
};



/**
  * This is the header for a trace.
  *
  * @short   Trace Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct TraceHeader
{
   /**
     * Frame rate (double converted to binary using translateToBinary()).
     *
     * @see translateToBinary
     * @see translateToDouble
     */
   card64 FrameRate;

   /**
     * Number of frames.
     */
   card32 Frames;

   /**
     * Number of layers.
     */
   card8 Layers;

   /**
     * Unused. Should be set to 0.
     */
   card8 pad01;

   /**
     * Unused. Should be set to 0.
     */
   card16 pad02;

   /**
     * Frame description array:
     * 0      .. Frames - 1       Layer #0 trace
     * Frames .. 2 * Frames - 1   Layer #1 trace
     * ...
     */
   FrameDescription Frame[0];
};



/**
  * This is the header for a trace.
  *
  * @short   Trace Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct UtilizationHeader
{
   /**
     * Utility function type.
     */
   card16 Type;

   /**
     * Number of utilization constants.
     */
   card8 MaxConstants;

   /**
     * Number of utilization constants.
     */
   card8 Constants;

   /**
     * Utilization weight.
     */
   card64 Weight;

   /**
     * Array of utilization constants
     * (double converted to binary using translateToBinary()).
     *
     * @see translateToBinary
     * @see translateToDouble
     */
   card64 Constant[0];


   // ====== Calculation methods ============================================
   /**
     * Calculate utilization size.
     *
     * @param maxConstants Maximum number of constants.
     * @return Utilization size.
     */
   static inline cardinal getUtilizationSize(const cardinal maxConstants);
};


/**
  * This is an entry of a resource/utilization list.
  *
  * @short   Resource Utilization Entry
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct ResourceUtilizationEntry
{
   /**
     * Utilization divided by 2^30.
     */
   card32 Utilization;

   /**
     * Frame rate.
     */
   card64 FrameRate;

   /**
     * Bandwidth (sum of all layers and for each layer).
     */
   card32 Bandwidth[0];
};



/**
  * This is the header for a resource/utilization list.
  *
  * @short   Resource Utilization Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct ResourceUtilizationHeader
{
   /**
     * Number of entries.
     */
   card16 Entries;

   /**
     * Number of layers.
     */
   card8 Layers;

   /**
     * Flags.
     */
   card8 Flags;

   /**
     * Frame position of this header. If refers to the *maximum* frame rate!
     */
   card32 Position;

   /**
     * Array of resource/utilization entires.
     */
   ResourceUtilizationEntry Entry[0];


   // ====== Calculation methods ============================================
   /**
     * Calculate resource/utilization list size.
     *
     * @param layers Number of layers.
     * @param maxPoints Maximum number of RU points.
     * @return Resource/utilization list size.
     */
   static inline cardinal getResourceUtilizationSize(
                             const cardinal layers,
                             const cardinal maxConstants);
};



/**
  * This is the header for an interval description.
  *
  * @short   Interval Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct IntervalHeader
{
   /**
     * Interval start position.
     */
   card32 Position;

   /**
     * Interval length.
     */
   card32 Length;

   /**
     * Number of layers.
     */
   card8 Layers;

   /**
     * Interval flags.
     */
   card8 Flags;

   /**
     * Unused. Should be set to 0.
     */
   card16 pad;

   /**
     * Total size of the interval description.
     */
   card32 IntervalDescriptionSize;

   /**
     * Offset to interval descriptions:
     * 0: Utilization header for frame rate utilization
     * 1  1 + (0 * Layers): Layer header für Layer #0
     * 2  2 + (0 * Layers): Empirical Envelope header für Layer #0
     * 3  3 + (0 * Layers): Frame count Empirical Envelope header for layer #0
     * 4: 1 + (1 * Layers): Layer header für Layer #1
     * 5: 2 + (1 * Layers): Empirical Envelope header für Layer #1
     * 6: 3 + (1 * Layers): Frame count Empirical Envelope header for layer #1
     * ...
     */
   card32 Offset[0];
   /*
     ====================================================================
     IMPORTANT NOTICE:
     Changes in offset mapping require change in getIntervalHeaderSize()
     and/or get*Offset() methods!!!
     ====================================================================
   */


   // ====== Offset calculation methods =====================================
   /**
     * Calculate interval header size.
     *
     * @param layers Layer count.
     * @return Interval header size.
     */
   static inline cardinal getIntervalHeaderSize(const cardinal layers);

   /**
     * Utilization header offset number.
     */
   static const cardinal offsetUH = 0;

   /**
     * Get layer header offset number.
     *
     * @param layer Layer.
     * @return Layer offset number.
     */
   inline cardinal getOffsetLH(const cardinal layer) const;

   /**
     * Get byterate empirical envelope offset number.
     *
     * @param layer Layer.
     * @return Byterate empirical envelope offset number.
     */
   inline cardinal getOffsetEEBR(const cardinal layer) const;

   /**
     * Get frame count empirical envelope offset number.
     *
     * @param layer Layer.
     * @return Frame count empirical envelope offset number.
     */
   inline cardinal getOffsetEEFC(const cardinal layer) const;
};



/**
  * This is the header for a layer description.
  *
  * @short   Layer Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct LayerHeader
{
   /**
     * Offset of frame size utilization header.
     */
   card32 FrameSizeUtilizationOffset;

   /**
     * Scalability (out of (0,1]) divided by 2^30.
     * Minimum FrameSize = Scalability * FrameSize.
     */
   card32 Scalability;
   
   /**
     * Layer flags.
     */
   card8 Flags;
   
   /**
     * Reserved byte.
     */
   card8 pad;
};



/**
  * This is an entry of the Position/Length/Interval index.
  *
  * @short   Layer Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct PositionLengthIntervalIndexEntry
{
   /**
     * Interval start position.
     */
   card32 Position;

   /**
     * Interval length.
     */
   card32 Length;

   /**
     * File position of interval header.
     */
   card32 Interval;
};



/**
  * This is the header of the Position/Length/Interval index.
  *
  * @short   Layer Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct PositionLengthIntervalIndexHeader
{
   /**
     * Number of entries.
     */
   card32 Entries;

   /**
     * Array of index entries.
     */
   PositionLengthIntervalIndexEntry Entry[0];
};


/**
  * This is an entry of the resource/utilization list index.
  *
  * @short   Resource Utilization List Index Entry
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct ResourceUtilizationListIndexEntry
{
   /**
     * Position (refering to *maximum* frame rate).
     */
   card32 Position;

   /**
     * Interval length in frame rate units.
     */
   card32 Length;

   /**
     * File position of the resource/utilization list.
     */
   card32 List;
};


/**
  * This is the resource/utilization list index header.
  *
  * @short   Resource Utilization List Index Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct ResourceUtilizationListIndexHeader
{
   /**
     * Number of entries.
     */
   card32 Entries;

   /**
     * Entries.
     */
   ResourceUtilizationListIndexEntry Entry[0];
};


/**
  * This is an entry of the frame rate index.
  *
  * @short   Layer Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct MainIndexEntry
{
   /**
     * Frame rate.
     */
   card64 FrameRate;

   /**
     * File position of trace.
     */
   card32 Trace;

   /**
     * File position of interval header.
     */
   card32 Intervals;
};



/**
  * This is the header of the frame rate index.
  *
  * @short   Main Index Header
  * @author  Thomas Dreibholz (Dreibholz@bigfoot.com)
  * @version 1.0
  */
struct MainIndexHeader
{
   /**
     * Number of entries.
     */
   card32 Entries;

   /**
     * Array of main index entries.
     */
   MainIndexEntry Entry[0];
};


}


#include "tdtf.icc"


#endif

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