ILMMpgDmx Interface

Data types:

DemuxFlagConstants

typedef enum DemuxFlagConstants 
{ 
   DemuxFlag_IgnoreCorruptedPackets = 1, /* Ignore corrupted packets */ 
} DemuxFlagConstants; 

StreamFlagConstants

typedef enum StreamFlagConstants 
{ 
   StreamFlag_IsImportant = 0x1, /* This stream is important. The demux will not start streaming until samples from this stream are received */ 
} StreamFlagConstants; 

The demux will send the EC_LOADSTATUS (0x43) event to the DirectShow graph and set lParam1 to a LOADSTATUSConstant enum value. These notifications might be sent before the graph is built, providing an opportunity to get a pointer to the demux interface in order to set the demux callback. For more information about when these notifications are sent, refer to the LOADSTATUSConstant enum documentation.

LOADSTATUSConstant

typedef enum LOADSTATUSConstant 
{ 
   AM_LOADSTATUS_PROGRAM_PACKET_RECEIVED = 0x100, /* This notification is sent when the demux identifies the number and type of elementary streams present in the current program. */ 
   AM_LOADSTATUS_PROGRAM_COUNT_DETECTED = 0x102, /* This event is fired when the demux identifies the number of programs available in the MPEG2 stream */ 
   AM_LOADSTATUS_PROGRAM_INFO_DETECTED = 0x103, /* This event is fired when the demux extra information on the programs is available in the MPEG2 stream */ 
} LOADSTATUSConstant; 

FindSampleConstants

typedef enum FindSampleConstants 
{ 
   FindSample_NearestKeyFrame = 0,  /* Search for nearest key frame.  */ 
   FindSample_NextKeyFrame = 1,     /* Search for next key frame.     */ 
   FindSample_PreviousKeyFrame = 2, /* Search for previous key frame. */ 
} FindSampleConstants; 

Interface Properties:

Interface Methods:

HRESULT GetKlvParser (long streamPID, ILMKlvParser **pVal);

Parameters

Description

Use this method to facilitate parsing of KLV data conforming to SMPTE 336M-2001. There might be more than one private data stream and you should use a different parser for each stream. You identify each stream by its PID (-Packet IDentifier-). The PID is usually the same as the streamPID passed to ILMMpgDmxCallback::DataAvailable , but you can pass any value as the streamPID.

The ILMKlvParser interface can be used to easily enumerate the KLV keys and for getting the KLV data. It keeps track of incomplete keys and enumerates them when you get sufficient data.

Returns

S_OK if successful

E _POINTER if ppszFilename is NULL.

E_OUTOFMEMORY if there is not enough memory to create the interface.

HRESULT ConvertPTSToStreamPosition(double PTS, double *pStreamPosition);

Parameters

Description

Use this method to convert a PTS for the current MPEG stream into a stream position (in seconds). The PTS must have come from the current stream; otherwise the conversion will be incorrect. In other words, you cannot use a mpeg demux instance to convert PTS timestamps coming from a stream inside another MPEG demux.

This method it is intended to be used to find the correct display time for extra data samples received through ILMMpgDmxCallback::DataAvailable as follows:

1. Call ConvertPTSToStreamPosition(PTS, &PTSStreamPosition) to fill PTSStreamPosition with the desired stream position.
2. Call get_StreamPosition(¤tStreamPosition) to find the current stream position. (Add the "get_" prefix as it is usually done in C++ programs)
3. Determine when to display the data:
   • if PTSStreamPosition >= currentStreamPosition, then the data is early (the usual case) and you need to wait for PTSStreamPosition - currentStreamPosition seconds before displaying it.
   • if PTSStreamPosition < currentStreamPosition, then the data is late and you should display it right away. This is usually an indication that the video and extra data streams are not multiplexed properly.

Returns

S_OK if successful

S_FALSE if it fails (in this case, *pCurrentPosition will be set to -1)

HRESULT ConvertStreamPositionToOffset(double streamPosition, double *pOffset);

Parameters

Description

Use this method to find the file offset of the start sample corresponding to a stream position (in seconds). The stream position must be from the current stream; otherwise, the conversion will be incorrect. In other words, you cannot use a mpeg demux instance to convert a stream position coming from a stream inside another MPEG demux.

This method is intended to be used in conjunction with FindSample to find the offset of a key frame. For example, to find the first key frame following 0.7sec point, you would call FindNextKeyFrame(pDemux, 0.7), where FindNextKeyFrame is like this:

double FindNextKeyFrame(ILMMpgDmx *pDemux, double startPosition) 
{ 
   double startOffset, keyFrameOffset; 
   // find the offset corresponding to the start position 
   pDemux->ConvertStreamPositionToOffset(startPosition, offset); 
   // find the offset of the key frame following startOffset + 1 
   // I added 1 to startOffset just in case there is a key frame at 0.7s 
   // If I do not add 1 and there is a key frame at 0.7s, FindNextKeyFrame would return 0.7 
   if(pDemux->FindSample(startOffset + 1, FindSample_NextKeyFrame, &keyFrameOffset) == S_OK) 
   { 
      // find the stream position corresponding to the key frame offset 
      pDemux->ConvertOffsetToStreamPosition(keyFrameOffset, &keyFramePosition); 
      return keyFramePosition; 
   } 
   else 
   { 
      return -1; // there is no key frame following this point 
   } 
} 

Returns

S_OK if successful

<> S_OK if the function fails (in this case pOffset will be left unchanged).

HRESULT ConvertOffsetToStreamPosition(double offset, double *pStreamPosition);

Parameters

Description

Use this method to find the stream position (in seconds) of the first sample following a file offset. The stream position must have come from the current stream; otherwise the conversion will be incorrect. In other words, you cannot use a mpeg demux instance to convert a stream position coming from a stream inside another MPEG demux.

This method is intended to be used in conjunction with FindSample to find the stream position of a key frame. See the ConvertStreamPositionToOffset method for more information and for an example.

Returns

S_OK if successful

<> S_OK if the function fails (in this case pStreamPosition will be left unchanged).

HRESULT RefreshPosition(long Flags);

Parameters

Description

Updates the values of the position properties  (BaseStreamXXX, CurrentStreamXXX, StartStreamXXX, FirstStreamXXX, LastStreamXXX), where XXX indicates be PTS, Time and Offset version of the properties.

This method is intended to be used to update all PTS, Time and Offset properties.

Important note: You MUST call this method, otherwise properties like CurrentStreamPTS, CurrentStreamTime and CurrentStreamOffset never get updated.

Here is the complete list of properties updated by this method:

BaseStreamPTS, CurrentStreamPTS, StartStreamPTS, FirstStreamPTS, LastStreamPTS

BaseStreamTime, CurrentStreamTime, StartStreamTime, FirstStreamTime, LastStreamTime

BaseStreamOffset, CurrentStreamOffset, StartStreamOffset, FirstStreamOffset, LastStreamOffset
 

Returns

S_OK if successful

S_FALSE if it fails

HRESULT ConvertPTSToFrame(double PTS, double *pFrame);

Parameters

Description

Converts a PTS value to a frame number.

Use this method to convert a PTS value for the current mpeg stream to a frame number. The PTS must have come from the current stream; otherwise the conversion will be incorrect. In other words, you cannot use a mpeg demux instance to convert PTS timestamps coming from a stream inside another MPEG demux.

Returns

S_OK if successful

S_FALSE if it fails

HRESULT ConvertFrameToPTS(double Frame, double *pPTS);

Parameters

Description

Converts a frame number value to a PTS value.

Use this method to convert a frame number for the current mpeg stream to a PTS value.

Returns

S_OK if successful

S_FALSE if it fails

HRESULT GetStreamInfo(long StreamIndex, long *pStreamPID, long *pStreamType, VARIANT *pStreamDescriptor);

Parameters

Description

Gets information for a specific stream.

Use this method to get the stream's PID, type and descriptor. Use the StreamCount property to determine the number of available elementary streams in the MPEG-2 stream.

It is best to call this method after receiving the EC_LOADSTATUS notification event with the AM_LOADSTATUS_PROGRAM_PACKET_RECEIVED parameter. See the Programming with the MPEG-2 Transport Demultiplexer topic for more details.

Returns

S_OK if successful

S_FALSE if it fails

HRESULT FindSample(double startOffset, FindSampleConstants searchFlags, double *pKeyFrameOffset);

Parameters

Description

Finds a particular video sample relative to a starting offset. The method is used to search for the nearest, previous or the following key frame relative to a starting offset.

The method will fail if there is no video stream.

Use the ConvertStreamPositionToOffset and ConvertOffsetToStreamPosition methods to convert between the file offset and the stream position (in seconds). Refer to ConvertStreamPositionToOffset for an example of how to use this method.

Returns

S_OK if successful

S_FALSE if there is no video stream or the video sample could not be found

VFW_E_NO_ALLOCATOR: the input pin is not connected

E_OUTOFMEMORY: out of memory

HRESULT GetProgramInfoAsLong(long nProgramIndex, ProgramInfoConstants nAttributeIndex, long* pVal);

Parameters

Description

Gets more information about a particular program. Note that not all ProgramInfoConstants values are supported. See the ProgramInfoConstants enumeration to see which attributes can have integer values.

You can use the ProgramCount property to find out how many programs are in the file. This determines the allowable values for the nProgramIndex parameter.

There might be updated information about the program info when the EVENTTYPE_PROGRAMINFO or AM_LOADSTATUS_PROGRAM_INFO_DETECTED notification is received.

Returns

S_OK if successful

DISP_E_BADINDEX if nProgramIndex is invalid.

E_INVALIDARG: nAttributeIndex is invalid or does not point to an attribute that has a corresponding long value.

HRESULT GetProgramInfoAsString(long nProgramIndex, ProgramInfoConstants nAttributeIndex, BSTR* pVal);

Parameters

Description

Gets more information about a particular program. Note that not all ProgramInfoConstants values might supported. See the ProgramInfoConstants enumeration to see which attributes can have string values.

You can use the ProgramCount property to find out how many programs are in the file. This determines the allowable values for the nProgramIndex parameter.

There might be updated information about the program info when the EVENTTYPE_PROGRAMINFO or AM_LOADSTATUS_PROGRAM_INFO_DETECTED notification is received. For example, detailed information like the channel name is received less often than the information about the number of programs. So when you first get the summary of detailed info, the program name might be generic if the demux has not yet encountered the extra information. Later on, when more information is received, the EVENTTYPE_PROGRAMINFO or AM_LOADSTATUS_PROGRAM_INFO_DETECTED notifications are sent so you know that there might be updated information. If you created menu items in your application indicating which programs are available, you might want to call this method again and update the information you displayed in the menu or status areas.

Returns

S_OK if successful

DISP_E_BADINDEX if nProgramIndex is invalid.

E_INVALIDARG: nAttributeIndex is invalid or does not point to an attribute that has a corresponding long value.