asf_demux.h

Sigma SMP8634 Mrua v. 2.8.2.0

/*****************************************
 Copyright © 2001-2003  
 Sigma Designs, Inc. All Rights Reserved
 Proprietary and Confidential
 *****************************************/

/**
  @file   asf_demux.h
  @brief  Demultiplexer for the Microsoft ASF file format.

@verbatim
  Input: Filename
  Output: Callbacks

  Usage:
    1. create a (struct asf_demux_callback_t)
    1. declare a (struct asf_demux_state_t*)
    2. call asf_demux_create
    2. populate the (struct asf_demux_callback_t)
    3. call asf_demux
    4. call asf_demux_destroy
    5. destroy the (struct asf_demux_callback_t)
@endverbatim

  Unsupported features:
    - Broadcast files
    - see Application_Specific_Object_Handler for unsupported headers

  @author Guillaume Etorre
  @date   2003-01-17
*/

#ifndef __ASF_DEMUX_H__
#define __ASF_DEMUX_H__

#include "../../rmdef/rmdef.h"

RM_EXTERN_C_BLOCKSTART


struct asf_demux_state_t;

/**

   Callback structure.
   Unused entries must be set to NULL.

*/

struct asf_demux_callback_t {

/**

  Callback to handle GUIDs not supported by asf_demux.

  Currently unsupported GUIDs include:
    - Header Extension Object
    - Script Command Object
    - Marker Object
    - Error Correction Object
    - Content Description Object
    - Extended Content Description Object
    - Type Specific Data Length in a Command-type Stream Properties Object
       in this last case only, the Data is Size bytes long

  All unsupported GUIDs are skipped by asf_demux after the callback is processed

  @param context
  @param GUID
    The GUID is transfered in the same byte order as in the ASF file.
  @param Size
    As read in the ASF file
  @param Data
    (Size - 24) bytes long (except for Type Specific Data Length
    in a ASF_Command_Media type ASF_Stream_Properties_Object).
*/
  
  void (*Application_Specific_Object_Handler)
       (
	void *context,
	unsigned char GUID[16],
	char *Name,
	unsigned char *Data,
	RMuint64 Partial_Size,                // bytes
	RMuint64 Size               // bytes
	);

/**

  Callback to handle the file properties.

  Called once at the beginning of the demux.

  @param context
  @param File_Size
    Size of the entire file. Invalid if Broadcast mode.
  @param Creation_Date
    See MSDN for details
  @param Data_Packets_Count
    Invalid if Broadcast mode.
  @param Play_Duration
    Time needed to play the file. Invalid if Broadcast mode.
  @param Send_Duration
    Time needed to send the file. 
    Invalid if Broadcast mode.
  @param Preroll
    Amount of time to buffer data before starting to play the file.
  @param Minimum_Data_Packet_Size
    Minimum size of a data packet.
    Should be equal to Maximum_Data_Packet_Size.
    Invalid if Broadcast mode.
  @param Maximum_Data_Packet_Size
    Maximum size of a data packet.
    Should be equal to Minimum_Data_Packet_Size.
    Invalid if Broadcast mode.
  @param Maximum_Bitrate
    Maximum bitrate for the entire file.
    Data packetization overhead is included in the count.
  @param Broadcast
    Specifies the file is currently being written.
    asf_demux does not currently support Broadcast files.
  @param Seekable
    Specifies the file is seekable. This either implies that 
    Maximum_Data_Packet_Size is equal to Minimum_Data_Packet_Size,
    or that a Simple Index object is present for each video stream.

*/
  void (*ASF_File_Properties_Handler)
       (
	void *context,
	RMuint64 File_Size,                 // bytes (invalid if Broadcast)
	RMuint64 Creation_Date,             // See MSDN Library
	RMuint64 Data_Packets_Count,        // (invalid if Broadcast)
	RMuint64 Play_Duration,             // 100-ns units (invalid if Broadcast)
	RMuint64 Send_Duration,             // 100-ns units (invalid if Broadcast)
	RMuint64 Preroll,                   // milliseconds
	unsigned long Minimum_Data_Packet_Size,       // bytes
	unsigned long Maximum_Data_Packet_Size,       // bytes
	unsigned long Maximum_Bitrate,                // bits/s
	unsigned char Broadcast,                      // boolean
	unsigned char Seekable                        // boolean
	);

/**

   Callback to receive bitrate information on the streams

   @param Stream_Number
   @param Average_Bitrate

*/

  void (*ASF_Stream_Bitrate_Properties_Handler)
       (
	void *context,
	unsigned char Stream_Number,                  // 1..127
	unsigned long Average_Bitrate                 // bits/s
	);
  
  /**

     Callback to create a new video stream

     @param context
     @param Stream_Number
     @param Compression_ID
       Type of compression, as in the biCompression
       field of a BITMAPINFOHEADER structure. See MSDN Library.
     @param Image_Width
     @param Image_Height
     @param *Codec_Specific_Data
     @param Codec_Specific_Data_Size
  */
  
  void (*ASF_Video_Stream_Properties_Handler)
       (
	void *context,
	unsigned char Stream_Number,                  // 1..127
	unsigned long Compression_ID,                 // See MSDN Library
	unsigned long Image_Width,                    // pixels
	unsigned long Image_Height,                   // pixels
	unsigned char *Codec_Specific_Data,
	unsigned long Partial_Codec_Specific_Data_Size,
	unsigned long Codec_Specific_Data_Size        // bytes
	);

/**
   Callback to create a new audio stream

   @param context
   @param Stream_Number
   @param Codec_ID
     Defined in the MSDN Library as the wFormatTag field
     of a WAVEFORMATEX structure
   @param Number_of_Channels
   @param Samples_Per_Second
   @param Bits_Per_Sample
   @param Codec_Specific_Data
   @param Codec_Specific_Data_Size
*/
  
  void (*ASF_Audio_Stream_Properties_Handler)
       (
	void *context,
	unsigned char Stream_Number,                  // 1..127
	unsigned short Codec_ID,                      // see MSDN Library
	unsigned short Number_of_Channels,
	unsigned long Samples_Per_Second,
	unsigned long Average_Number_of_Bytes_Per_Second,
 	unsigned short Block_Alignment,
	unsigned short Bits_Per_Sample,
	unsigned char *Codec_Specific_Data,
	unsigned long Partial_Codec_Specific_Data_Size,
	unsigned long Codec_Specific_Data_Size        // bytes
	);

/**

   Callback to signal mutually exclusive bitstreams.

   Each value of mutex_index is associated with multiple
   Stream_Number values. Only one Stream_Number should be
   used per mutex_index value.
   
   @param context
   @param mutex_index
   @param Stream_Numbers_Count
   Constant for a given mutex_index
   @param bitrate_exclusion
   Signals that the mutually exclusive streams encode
   the same content at different bitrates.
   Constant for a given mutex_index
   @param Stream_Number
*/
  
  void (*ASF_Bitrate_Mutual_Exclusion_Handler)
       (
	void *context,
	unsigned long mutex_index,
	unsigned short Stream_Numbers_Count,
	unsigned char bitrate_exclusion,              // boolean
	unsigned char Stream_Number                   // 1..127
	);

/**
	@param context
	@param Stream_Number
	@param buf
	  Pointer to the payload buffer
	@param size
	  Size of the payload buffer
	@param Is_Key_Frame
	@param Media_Object_Number
	  Number of the Audio or Video frame.
	@param Media_Object_Number_valid
	@param Presentation_Time
	  Presentation Time of the Media Object the payload belongs to.
	@param Presentation_Time_valid
*/
  
   int (*ASF_Payload_Handler)
       (
	void *context,
	unsigned char Stream_Number,                  // 1..127
	unsigned char *buf,
	unsigned long size,                           // bytes
	unsigned char Is_Key_Frame,                   // boolean
	unsigned long Media_Object_Number,
	unsigned char Media_Object_Number_valid,      // boolean
	unsigned long Presentation_Time,              // milliseconds
	unsigned char Presentation_Time_valid         // boolean
	);

/**

   Callback to create an index entry.

   There is one index per video stream;
   they are ordered by Stream Number.
   Each index contains multiple index entries,
   separated in time by Index_Entry_Time_Interval
   and has a unique index_index. 
   Each index entry contains a Packet_Number
   and a Packet_Count.

   @param context
   @param index_index
   @param Index_Entries_Count
     Constant for a given index_index
   @param Index_Entry_Time_Interval
     Constant for a given index_index
   @param Packet_Number
     Number of the data packet associated with this entry.
     For video streams containing both key frames and
     non-key frames, this field should point to the
     closest past key frame.
   @param Packet_Count
     Number of data packets to send starting at Packet_Number
     to reach the index entry time.
*/
  
  void (*ASF_Simple_Index_Entry_Handler)
       (
	void *context,
	unsigned char index_index,
	unsigned long Index_Entries_Count,
	RMuint64 Index_Entry_Time_Interval, // 100-ns units
	unsigned long Packet_Number,
	unsigned short Packet_Count
	);

/**

   Callback to fetch bitstream.

   @param context
   @param buffer
     On input, the address of the used buffer
     On output, the address of the new buffer
   @param size
     On output, contains the size of the new buffer
*/
  
  int (*ASF_get_bitstream)
       (
	void *context,
	unsigned char **buffer,
	RMuint64 *size
	);
};

/**

  asf_demux constructor

  Allocates storage space for the asf_demux state structure.

  @param callbacks
    Pointer to the callback stucture. The callbacks
    can change after the constructor is called, but the
    pointer to the callback structure must not.
  @param context
    Pointer which is sent back to each callback.

*/

struct asf_demux_state_t *asf_demux_create
(
 struct asf_demux_callback_t *callbacks, 
 void *context
 );

/**

  asf_demux destructor

  Frees the storage space for the asf_demux state structure.

  Must be called before destroying the callback structure.

  @param asf_demux_state

*/

void asf_demux_destroy(struct asf_demux_state_t *asf_demux_state);

/**

  asf_demux entry point

  @param asf_demux_state
  @param filename

*/
int asf_demux
(
 struct asf_demux_state_t *asf_demux_state
 );

RM_EXTERN_C_BLOCKEND

#endif // __ASF_DEMUX_H__