Structures

This section describes the Microsoft® DirectShow™ structures.

Structure	Description
ALLOCATOR_PROPERTIES	Contains the allocator's count, size, alignment, and prefix properties.
AM_DVD_RENDERSTATUS	Provides status (failure) codes for IDvdGraphBuilder::RenderDvdVideoVolume.
AM_MEDIA_TYPE	Describes a media sample type.
AM_SAMPLE2_PROPERTIES	Describes the properties of a generic media sample.
AMOVIESETUP_FILTER	Contains filter information for registering a filter.
AMOVIESETUP_MEDIATYPE	Contains media type information for registering a filter.
AMOVIESETUP_PIN	Contains pin information for registering a filter.
AM_STREAM_INFO	Contains start and stop information given to a pin.
AMVPDATAINFO	Specifies the data-specific characteristics of the VP input stream.
AMVPDIMINFO	Specifies the dimensional characteristics of the VP input stream.
AMVPSIZE	Specifies the width and height for a VP image.
DVD_ATR	Specifies DVD attributes.
DVD_TIMECODE	Contains DVD timecode in hours, minutes, seconds, and frames.
FILTER_INFO	Contains information about a filter.
PIN_INFO	Contains information about a pin.
POSITION	Placeholder for linked lists.
Quality	Describes a quality message by indicating Flood or Famine in the renderer and specifying the percentage of frames to drop or add to optimize the renderer's performance.
REGFILTER	Describes a filter in the registry.
REGFILTER2	Describes a filter for registration through the IFilterMapper2 interface.
REGFILTERPINS2	Contains information for registering a filter through the IFilterMapper2 interface.
REGPINMEDIUM	Describes a pin medium (as defined in the Windows NT DDK) for registration through the IFilterMapper2 interface.
REGFILTERPINS	Contains pin information for registering a filter.
REGPINTYPES	Contains media type information for registering a filter.

The following structure maintains information about graphics device interface (GDI) bitmaps and device-independent bitmaps (DIBs). This is used solely by the CImageAllocator, CImageSample, and CDrawImage window utility classes.

Structure	Description
DIBDATA	Contains information about each DIB.

The following structures maintain information about video, as well as video capture and compression.

Structure	Description
TRUECOLORINFO	Maintains color information.
ANALOGVIDEOINFO	Maintains information about the format of the analog video signal.
AUDIO_STREAM_CONFIG_CAPS	Contains information about all possible audio formats supported.
COLORKEY	Communicates color key information between the renderer and another filter.
MPEG1VIDEOINFO	Contains additional MPEG-1 video system information.
MPEG2VIDEOINFO	Contains additional MPEG-2 video system information.
TIMECODE	Contains basic timecode frame count information.
TIMECODE_SAMPLE	Contains complete timecode information.
VIDEO_STREAM_CONFIG_CAPS	Contains information about possible connections.
VIDEOINFO	Contains information that specifies a video image and its color palette and bitmasks.
VIDEOINFOHEADER	Describes the bitmap and color information for a video image.
VIDEOINFOHEADER2	Describes the bitmap and color information for a video image, including interlace, copy protection, and pixel aspect ratio information.

---

ALLOCATOR_PROPERTIES

Structures

Contains the allocator's count, size, alignment, and prefix properties.

typedef struct _AllocatorProperties {
	long cBuffers;
	long cbBuffer;
	long cbAlign;
	long cbPrefix;
} ALLOCATOR_PROPERTIES;

Members

cBuffers

Count of buffers at this allocator.

cbBuffer

Size of each buffer in bytes, excluding any prefix.

cbAlign

Alignment of the buffer; buffer start will be aligned on a multiple of this value.

cbPrefix

Each buffer is preceded by a prefix of this many bytes.

Remarks

The CMediaSample::GetPointer member function points to the beginning of the buffer, not including the prefix bytes designated by cbPrefix.

The alignment is applied to the prefix data, if any. If a nonzero prefix is used, the beginning of the prefix is aligned according to cbAlign. Since the buffer pointer returned by IMediaSample::GetPointer points to the area immediately following the prefix, the cbPrefix address (the value returned by IMediaSample::GetPointer minus cbPrefix) should be aligned on an address that is a multiple of cbAlign bytes.

---

AM_DVD_RENDERSTATUS

Structures

Provides status (failure) codes for IDvdGraphBuilder::RenderDvdVideoVolume.

typedef struct {
HRESULT hrVPEStatus;	
BOOL    bVPEFailed;          
	BOOL    bDVDVolInvalid;      
	BOOL    bDVDVolUnknown;      
	BOOL    bNoLine21In;
	BOOL    bNoLine21Out;           
	int     iNumStreams;         
	int     iNumStreamsFailed;   
	DWORD   dwFailedStreamsFlag; 
} AM_DVD_RENDERSTATUS;

Members

hrVPEStatus

Video port extension (VPE) error code. Zero indicates success; any other value is failure.

bVPEFailed

TRUE if the caller didn't set the AM_DVD_NOVPE flag in the RenderDvdVideoVolume call and VPE mixing failed; FALSE otherwise.

bDVDVolInvalid

TRUE if the specified DVD volume to be played does not exist; FALSE otherwise.

bDVDVolUnknown

TRUE if no DVD volume is specified or if it isn't found; FALSE otherwise.

bNoLine21In

TRUE if the video decoder doesn't produce Line 21 (closed captioning) data; FALSE otherwise.

bNoLine21Out

TRUE if the video decoder can't show decoded Line 21 data as CC on video; FALSE otherwise.

iNumStreams

Number of DVD streams to render.

iNumStreamsFailed

Number of streams that failed to render.

dwFailedStreamsFlag

Combination of AM_DVD_STREAM_FLAGS flags indicating which streams failed.

See Also

IDvdGraphBuilder::RenderDvdVideoVolume

---

AM_MEDIA_TYPE

Structures

Describes a media sample type.

typedef struct  _MediaType
    {
    GUID      majortype;
    GUID      subtype;
    BOOL      bFixedSizeSamples;
    BOOL      bTemporalCompression;
    ULONG     lSampleSize;
    GUID      formattype;
    IUnknown  *pUnk;
    ULONG     cbFormat;
    /* [size_is] */ BYTE __RPC_FAR *pbFormat;
    } AM_MEDIA_TYPE;

Members

majortype

Major type of the media sample.

subtype

Subtype of the media sample.

bFixedSizeSamples

If TRUE, samples are of a fixed size.

bTemporalCompression

If TRUE, samples are compressed.

lSampleSize

Size of the sample in bytes.

formattype

Registered (GUID) format type.

pUnk

Pointer to the IUnknown interface.

cbFormat

Size of the format section of the media type.

pbFormat

Pointer to the format section of the media type. The layout of this is determined by the format type GUID. Format types include the following:

Format type	Structure pointed to
FORMAT_MPEGVideo	MPEG1VIDEOINFO
FORMAT_VideoInfo	VIDEOINFOHEADER
FORMAT_WaveFormatEx	WAVEFORMATEX
FORMAT_MPEG2Video	MPEG2VIDEOINFO
FORMAT_VideoInfo2	VIDEOINFOHEADER2

---

AM_SAMPLE2_PROPERTIES

Structures

Describes the properties of a generic media sample.

typedef struct tagAM_SAMPLE2_PROPERTIES {
    DWORD    cbData;
    DWORD    dwTypeSpecificFlags;
    DWORD    dwSampleFlags;
    LONG     lActual;
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    DWORD    dwStreamId;
    AM_MEDIA_TYPE *pMediaType;
    BYTE    *pbBuffer;
    LONG     cbBuffer;
} AM_SAMPLE2_PROPERTIES;

Members

cbData

Length of property data for extensibility; number of bytes including this field.

dwTypeSpecificFlags

Type-specific flag data. These flags are defined separately for each media type. Default is zero.

dwSampleFlags

Flags bits defined by the AM_SAMPLE_PROPERTY_FLAGS enumerated data type. All undefined bits are reserved (set them to zero, and do not copy them).

lActual

Length of data in the buffer pointed to by the pbBuffer member.

tStart

Start time if valid.

tStop

Stop time if valid.

dwStreamId

Stream identifier. Stream 0 is the normal media transport. Stream 1 is control. Currently, only Stream 0 is used. Filters should pass any other stream ID directly to their output pins without processing.

pMediaType

Copy of the media type. It becomes invalid after the sample has been released.

pbBuffer

Pointer to the buffer. The pointer becomes invalid after the sample is released.

cbBuffer

Total length of the buffer pointed to by pbBuffer, in bytes.

Remarks

The IMediaSample2 interface uses this structure.

---

AMOVIESETUP_FILTER

Structures

Contains filter information for registering a filter.

typedef struct _AMOVIESETUP_FILTER
{
    const CLSID * clsID;
    LPWSTR     strName;
    DWORD      dwMerit;
    UINT       nPins;
    LPAMOVIESETUP_PIN lpPin;
}
AMOVIESETUP_FILTER

Members

clsID

Class identifier of the filter.

strName

Name of the filter.

dwMerit

Merit used by the GraphBuilder object when constructing a filter graph.

nPins

Number of pins on the filter.

lpPin

AMOVIESETUP_PIN structure providing pin information.

---

AMOVIESETUP_MEDIATYPE

Structures

Media type information for registering a filter.

typedef struct _AMOVIESETUP_MEDIATYPE
{
    const CLSID * clsMajorType;
    const CLSID * clsMinorType;
} AMOVIESETUP_MEDIATYPE;

Members

clsMajorType

Major media type supported by the filter.

clsMinorType

Minor media type supported by the filter.

---

AMOVIESETUP_PIN

Structures

Pin information for registering a filter.

typedef struct _AMOVIESETUP_PIN
{
    LPWSTR           strName;
    BOOL             bRendered;
    BOOL             bOutput;
    BOOL             bZero;
    BOOL             bMany;
    const CLSID *    clsConnectsToFilter;
    LPWSTR           strConnectsToPin;
    UINT             nMediaTypes;
    LPAMOVIESETUP_MEDIATYPE lpMediaType;
}
AMOVIESETUP_PIN;

Members

strName

Name of the pin.

bRendered

Set to TRUE if the filter renders this input; otherwise, set to FALSE.

bOutput

Flag to indicate if this pin is an output pin.

bZero

If the filter has zero instances of this pin, set this to TRUE; otherwise, set to FALSE. For example, a decompression filter might choose not to create a sound output pin for a movie without a sound track.

bMany

If the filter has many instances of this pin, set this to TRUE; otherwise, set to FALSE. For example, a mixer might have multiple instances of its input pin.

clsConnectsToFilter

CLSID of the filter to which this filter connects in a filter graph.

strConnectsToPin

Name of the pin to which this pin connects in a filter graph.

nMediaTypes

Number of media types supported by this pin.

lpMediaType

AMOVIESETUP_MEDIATYPE structure providing media type information.

---

AM_STREAM_INFO

Structures

Contains start and stop information given to a pin.

typedef struct {
    REFERENCE_TIME tStart;
    REFERENCE_TIME tStop;
    DWORD dwStartCookie;
    DWORD dwStopCookie;
    DWORD dwFlags;
} AM_STREAM_INFO;

Members

tStart

Time at which streaming will start.

tStop

Time at which streaming will stop.

dwStartCookie

Number that will be given to the application that ordered the start, when the event occurs.

dwStopCookie

Number that will be given to the application that ordered the stop, when the event occurs.

dwFlags

AM_STREAM_INFO_FLAGS enumeration type flag.

Remarks

Access this structure through the IAMStreamControl interface.

---

AMVPDATAINFO

Structures

Specifies the data-specific characteristics of the VP input stream.

typedef struct _AMVPDATAINFO{
DWORD dwSize;	 
DWORD dwMicrosecondsPerField; 
AMVPDIMINFO amvpDimInfo;	 
DWORD dwPictAspectRatioX;	
DWORD dwPictAspectRatioY;	
BOOL bEnableDoubleClock;	
BOOL bEnableVACT;		
BOOL bDataIsInterlaced;		
LONG lHalfLinesOdd;		
BOOL bFieldPolarityInverted;	
DWORD dwNumLinesInVREF;
LONG lHalfLinesEven;  		
DWORD dwReserved1;		
} AMVPDATAINFO, *LPAMVPDATAINFO;

Members

dwSize

Size of the structure, in bytes.

dwMicrosecondsPerField

Time taken by each field.

amvpDimInfo

Dimensional information.

dwPictAspectRatioX

The X dimension of picture aspect ratio.

dwPictAspectRatioY

The Y dimension of picture aspect ratio.

bEnableDoubleClock

Video port should enable double clocking.

bEnableVACT

Video port should use an external VACT signal.

bDataIsInterlaced

Indicates that the signal is interlaced.

lHalfLinesOdd

Number of half lines in the odd field.

bFieldPolarityInverted

Video port should invert the field polarity.

dwNumLinesInVREF

Number of lines of data in VREF.

lHalfLinesEven

Number of half lines in the even field.

dwReserved1

Reserved for future use.

---

AMVPDIMINFO

Structures

Specifies the dimensional characteristics of the VP input stream.

typedef struct _AMVPDIMINFO{
DWORD dwFieldWidth;	 
DWORD dwFieldHeight;	 
DWORD dwVBIWidth;	 
DWORD dwVBIHeight;	
RECT rcValidRegion;	
} AMVPDIMINFO, *LPAMVPDIMINFO;

Members

dwFieldWidth

Field width of the data.

dwFieldHeight

Field height of the data.

dwVBIWidth

Width of the VBI data.

dwVBIHeight

Height of the VBI data.

rcValidRegion

Valid rectangle, used for cropping.

---

AMVPSIZE

Structures

Specifies the width and height for a VP image.

typedef struct _AMVPSIZE{
DWORD dwWidth;
DWORD dwHeight;
} AMVPSIZE, *LPAMVPSIZE;

Members

dwWidth

Width, in pixels.

dwHeight

Height.

Remarks

The context could be anything such as scaling, cropping, and so on.

---

ANALOGVIDEOINFO

Structures

Maintains information about the format of the analog video signal.

typedef struct tagAnalogVideoInfo {
    RECT            rcSource;           
    RECT            rcTarget;           
    DWORD           dwActiveWidth;      
    DWORD           dwActiveHeight;     
    REFERENCE_TIME  AvgTimePerFrame;    
} ANALOGVIDEOINFO;

Members

rcSource

Source video rectangle.

rcTarget

Destination target rectangle.

dwActiveWidth

Source video width.

dwActiveHeight

Source video height (483 for NTSC, 575 for PAL/SECAM).

AvgTimePerFrame

Average time per frame in 100-nanosecond units.

Remarks

Filters using this format usually pass the video signal using a hardware-based connection rather than using memory-based transports.

An example of a definition of an analog video media type connection would be a connection of NTSC video using "M" color encoding. This would use a major media type of MEDIATYPE_AnalogVideo, a subtype of MEDIASUBTYPE_AnalogVideo_NTSC_M, and a format type of FORMAT_AnalogVideo.

---

AUDIO_STREAM_CONFIG_CAPS

Structures

Contains information about all possible audio formats supported.

typedef struct _AUDIO_STREAM_CONFIG_CAPS {
        GUID guid;
        ULONG MinimumChannels;
        ULONG MaximumChannels;
        ULONG ChannelsGranularity;
        ULONG MinimumBitsPerSample;
        ULONG MaximumBitsPerSample;
        ULONG BitsPerSampleGranularity;
        ULONG MinimumSampleFrequency;
        ULONG MaximumSampleFrequency;
        ULONG SampleFrequencyGranularity;
    } AUDIO_STREAM_CONFIG_CAPS;

Members

guid

Will be set to MEDIATYPE_Audio to indicate an audio sample.

MinimumChannels

Minimum number of channels this pin supports.

MaximumChannels

Maximum number of channels this pin supports (for example, 2 for stereo).

ChannelsGranularity

Granularity of the channels. For example, you could specify channels 2 through 4 in steps of 2.

MinimumBitsPerSample

Minimum bits per sample.

MaximumBitsPerSample

Maximum bits per sample.

BitsPerSampleGranularity

Granularity of the bits. For example, you could specify 8 bits or 32 bits in steps of 8.

MinimumSampleFrequency

Minimum frequency allowed.

MaximumSampleFrequency

Maximum frequency allowed.

SampleFrequencyGranularity

Granularity of the frequency. For example, you could specify 11025 to 44100Hz in steps of 11025

Remarks

This structure is returned by an audio capture or compression filter.

See Also

IAMStreamConfig::GetStreamCaps

---

COLORKEY

Structures

Communicates color key information between the renderer and another filter.

typedef struct tagCOLORKEY
    {
    DWORD           KeyType;
    DWORD           PaletteIndex;
    COLORREF        LowColorValue;
    COLORREF        HighColorValue;
    }    COLORKEY;

Members

KeyType

Key type. Can be CK_NOCOLORKEY, CK_INDEX, or CK_RGB. CK_INDEX and CK_RGB can be logically combined.

PaletteIndex

Palette index.

LowColorValue

Lowest RGB color value.

HighColorValue

Highest RGB color value.

Remarks

The video renderer supports a data transport accessed through the IOverlay interface. This will typically be used by hardware decoder filters that need the renderer to communicate where to put the data rather than requiring the renderer to draw the data. One mechanism for communicating where to put the images is by using a color key. This structure is used by a filter (typically a hardware decoder) to describe color key requirements to the video renderer.

---

DIBDATA

Structures

Maintains information about each GDI DIB.

typedef struct tagDIBDATA {
    LONG        PaletteVersion;  
    DIBSECTION  DibSection;     
    HBITMAP     hBitmap;        
    HANDLE      hMapping;      
    BYTE        *pBase;         
} DIBDATA;

Members

PaletteVersion

Current palette version in use.

DibSection

Details of DIB section allocated.

hBitmap

Handle to bitmap for drawing.

hMapping

Handle to shared memory block.

pBase

Pointer to base memory address.

Remarks

When the allocator creates a sample, it allocates a DIBSECTION to the sample. When a window receives a sample, it can call the Win32 BitBlt function to pass the sample from one device context to another device context. This is a mechanism for the image allocator, an image sample, and the draw class to pass bitmap information to each other.

---

DVD_ATR

Structures

Specifies DVD attributes.

typedef struct tagDVD_ATR 
{
    ULONG    ulCAT;     
    BYTE    pbATRI[768];
} DVD_ATR;

Members

ulCAT

VMG_CAT if this is for a volume; or VTS_CAT if this is for a Video Title Set (VTS)

pbATRI

All stream attributes for menu and title from bytes 256 to 1023 of VMGI or VTSI.

Remarks

Refer to the DVD-Video specification to parse these structures.

---

DVD_TIMECODE

Structures

Contains DVD timecode in hours, minutes, seconds, and frames.

typedef struct tagDVD_TIMECODE")
{
   ULONG Hours1   :4; 
   ULONG Hours10  :4; 

   ULONG Minutes1 :4; 
   ULONG Minutes10:4; 

   ULONG Seconds1 :4; 
   ULONG Seconds10:4; 

   ULONG Frames1  :4; 
   ULONG Frames10 :2; 

   ULONG FrameRateCode:2; 
} DVD_TIMECODE;

Members

Hours1

Hours.

Hours10

Tens of hours.

Minutes1

Minutes.

Minutes10

Tens of minutes.

Seconds1

Seconds.

Seconds10

Tens of seconds.

Frames1

Frames.

Frames10

Tens of frames.

FrameRateCode

Frames per second dropped and not dropped as indicated by DVD_FRAMERATE.

Remarks

DVD Timecode is binary coded decimal (BCD) encoded in the format 0xHhMmSsFf, where

H is tens of hours

h is hours

M is tens of minutes

m is minutes

S is tens of seconds

s is seconds

F is tens of frames

f is frames

---

FILTER_INFO

Structures

Contains information about a filter.

typedef struct  _FilterInfo
    {
    WCHAR achName[ 128 ];
    IFilterGraph __RPC_FAR *pGraph;
    }     FILTER_INFO;

Members

achName

Name of the filter.

pGraph

Pointer to the IFilterGraph interface to which the filter is connected.

---

MPEG1VIDEOINFO

Structures

Describes an MPEG-1 video stream.

typedef struct tagMPEG1VIDEOINFO {
    VIDEOINFOHEADER hdr;
    DWORD           dwStartTimeCode;
    DWORD           cbSequenceHeader;
    BYTE            bSequenceHeader[1];
} MPEG1VIDEOINFO;

Members

hdr

Compatible with VIDEOINFOHEADER.

dwStartTimeCode

25-bit "group-of-pictures" time code at start of data.

cbSequenceHeader

Length in bytes of bSequenceHeader.

bSequenceHeader

Sequence header including quantization matrices, if any.

---

MPEG2VIDEOINFO

Structures

Describes an MPEG-2 video stream.

typedef struct tagMPEG2VIDEOINFO {
    VIDEOINFOHEADER2    hdr;
    DWORD               dwStartTimeCode;   
    DWORD               cbSequenceHeader;     
    DWORD               dwProfile;     
    DWORD               dwLevel;            
    DWORD               dwFlags;            
    DWORD               dwSequenceHeader[1];     
} MPEG2VIDEOINFO;

Members

hdr

Compatible with VIDEOINFOHEADER2.

dwStartTimeCode

25-bit "group-of-pictures" time code at start of data (not used for DVD).

cbSequenceHeader

Length in bytes of dwSequenceHeader (zero for DVD).

dwProfile

MPEG2Profile enumerated type member.

dwLevel

MPEG2Level enumerated type member.

dwFlags

Flag indicating preferences. Set one or a combination of the following values:

Value	Description
AMMPEG2_DoPanScan	If set, the MPEG-2 video decoder should crop the output image based on pan-scan vectors in picture_display_extension and change the picture aspect ratio accordingly.
AMMPEG2_DVDLine21Field1	If set, the MPEG-2 decoder must be able to produce an output pin for DVD style closed-captioned data found in the Group Of Pictures (GOP) layer of field 1.
AMMPEG2_DVDLine21Field2	If set, the MPEG-2 decoder must be able to produce an output pin for DVD style closed-captioned data found in the GOP layer of field 2.
AMMPEG2_SourceIsLetterboxed	If set, indicates that black bars have been encoded in the top and bottom of the video.
AMMPEG2_FilmCameraMode	If set, indicates "film mode" used for 625/50 content. If cleared, indicates that "camera mode" was used.

Note, set undefined flags to zero or connection will be rejected.

dwSequenceHeader

Sequence header including quantization matrices, if any.

---

PIN_INFO

Structures

Contains information about a pin.

typedef struct  _PinInfo
    {
    IBaseFilter  *pFilter;
    PIN_DIRECTION dir;
    WCHAR achName[ 128 ];
    }        PIN_INFO;

Members

pFilter

Pointer to the IBaseFilter interface of the owning filter.

dir

Direction of the pin (input or output).

achName

Name of the pin.

---

POSITION

Structures

Placeholder for a linked list.

struct __POSITION { int unused; };
typedef __POSITION* POSITION;

Members

unused

Integer value that specifies the location of an item in a linked list.

Remarks

This structure can point to any element in a linked list, including null elements (such as an end-of-list marker). This structure will, however, become invalid if you delete the item it points to.

When you perform operations that return a POSITION pointer on a single list element, a successful operation sets it to an appropriate non-null value, while null indicates that the items position could not be found. When you perform operations on the entire list, the pointer represents a Win32 BOOLEAN value, where TRUE indicates success and FALSE indicates failure.

See Also

CBaseList::GetHeadPositionI, CBaseList::GetTailPositionI

---

Quality

Structures

Describes a quality message by indicating Flood or Famine in the renderer and specifying the percentage of frames to drop or add to optimize the renderer's performance.

typedef struct{
    QualityMessageType Type;
    long                Proportion;
    REFERENCE_TIME       Late;
    REFERENCE_TIME       TimeStamp;
                           } Quality;

Members

Type

Either Famine or Flood, indicating that a downstream filter needs more or less data.

Proportion

Value that specifies the rate at which DirectShow should continue to send media samples. The base value is 1000, which indicates there should be no change. A percentage increase or decrease from 1000 indicates the percentage of frames to add or drop. If this value is 800, for example, DirectShow will drop 20 percent of the incoming frames to match the renderer's speed.

Late

If a famine exists downstream, this is the amount of time by which the stream is lagging.

TimeStamp

Value that specifies the time when DirectShow created this structure, which is usually the start time on a video sample.

---

REGFILTER

Structures

Identifies a filter in the registry.

typedef struct {
    CLSID Clsid;             
    LPWSTR Name;           
} REGFILTER;

Members

Clsid

Class identifier of the filter.

Name

Name of the filter.

---

TIMECODE

Structures

Contains basic timecode frame count information.

typedef struct tagTIMECODE {
		WORD	wFrameRate;	
		WORD	wFrameFract;	
		DWORD	dwFrames;
}TIMECODE;

Members

wFrameRate

Number of frames per second. Specify with one of the following values:

Setting	Description
ED_FORMAT_SMPTE_30	30 frames per second.
ED_FORMAT_SMPTE_30DROP	30 frames per second drop frame (actual rate 29.97 fps).
ED_FORMAT_SMPTE_25	25 frames per second.
ED_FORMAT_SMPTE_24	24 frames per second.

wFrameFract

Fractional frame. Full scale is 0x1000.

dwFrames

Timecode value as a binary framecount.

Remarks

Fractional frame can be used to indicate temporal offset into frame when timecode was actually read from an external device; for example, wFrameFract=0x7ff means the timecode value was read from the device at the end of the first video field.

Note Because timecode commonly enters or leaves computer systems as ASCII values, conversion helper methods that convert the ASCII values to and from binary framecounts are supplied in the sample filter.

---

TIMECODE_SAMPLE

Structures

Contains complete timecode information.

typedef struct tagTIMECODE_SAMPLE {
	LONGLONG	qwTick;		
	TIMECODE	timecode;	
	DWORD		dwUser;	
	DWORD		dwFlags;
} TIMECODE_SAMPLE;

Members

qwTick

Reference time, in 100-nanosecond units.

timecode

TIMECODE structure.

dwUser

Packed SMPTE userbits.

dwFlags

Timecode flag masks. Specify one or more of the following:

Value	Meaning
AM_TIMECODE_FLAG_FCM	Frame code mode; 0 = nondrop; 1 = drop.
AM_TIMECODE_FLAG_CF	Color frame flag.
AM_TIMECODE_FLAG_FIELD	Field flag.
AM_TIMECODE_FLAG_DF	Drop frame flag (from flags in actual timecode on external media).
AM_TIMECODE_COLORFRAME	Which frame in color sequence.
AM_TIMECODE_COLORSEQUENCE	Duration in frames of complete sequence.
AM_TIMECODE_FILMSEQUENCE_TYPE	One of FILM_SEQUENCE_XXX defines.

Remarks

The upper 16 bits in dwFlags are reserved for future use — set to zero.

---

TRUECOLORINFO

Structures

Contains color palette and bitmask information for a video image.

typedef struct tag_TRUECOLORINFO {
    DWORD dwBitMasks[iMASK_COLORS];
    RGBQUAD bmiColors[iPALETTE_COLORS];
} TRUECOLORINFO;

Members

dwBitMasks[iMASK_COLORS]

Array of color masks (one per color element).

bmiColors[iPALETTE_COLORS]

Array of palette colors.

Remarks

This structure is not used for some RGB formats. For more information about which fields are valid under different circumstances, see the Microsoft Win32® documentation for BITMAPINFO.

See Also

VIDEOINFO

---

VIDEO_STREAM_CONFIG_CAPS

Structures

Contains information about possible connections.

typedef struct  _VIDEO_STREAM_CONFIG_CAPS
    {
    GUID guid;
    ULONG VideoStandard;
    SIZE InputSize;
    SIZE MinCroppingSize;
    SIZE MaxCroppingSize;
    int CropGranularityX;
    int CropGranularityY;
    int CropAlignX;
    int CropAlignY;
    SIZE MinOutputSize;
    SIZE MaxOutputSize;
    int OutputGranularityX;
    int OutputGranularityY;
    int StretchTapsX;
    int StretchTapsY;
    int ShrinkTapsX;
    int ShrinkTapsY;
    LONGLONG MinFrameInterval;
    LONGLONG MaxFrameInterval;
    LONG MinBitsPerSecond;
    LONG MaxBitsPerSecond;
    }	VIDEO_STREAM_CONFIG_CAPS;

Members

guid

Will set MEDIATYPE_Video to indicate a video sample.

VideoStandard

The analog video standard supported. Set in the AnalogVideoStandard enumeration type (0 if not supported).

InputSize

Size of the incoming signal, expressed through the Win32 SIZE structure as the image rectangle's width and height in pixels. For a compressor, the size is taken from the width and height members of the Win32 BITMAPINFOHEADER structure in the input pin's AM_MEDIA_TYPE structure. For a capture filter, the size is the largest signal the filter can digitize with every pixel remaining unique.

MinCroppingSize

Smallest cropping rectangle allowed, as specified in the VIDEOINFOHEADER structure's rcSource member.

MaxCroppingSize

Largest cropping rectangle allowed, as specified in the VIDEOINFOHEADER structure's rcSource member.

CropGranularityX

Granularity of the cropping size. For example, you could specify that the only valid widths are an even multiple of four.

CropGranularityY

Granularity of the cropping size. For example, you could specify that the only valid heights are an even multiple of four.

CropAlignX

Alignment of the cropping rectangle inside InputSize. For example, you could specify that rectangles must start on a boundary that is a multiple of four.

CropAlignY

Alignment of the cropping rectangle inside InputSize. For example, you could specify that rectangles must start on a boundary that is a multiple of four.

MinOutputSize

Smallest bitmap this pin can produce.

MaxOutputSize

Largest bitmap this pin can produce.

OutputGranularityX

Granularity of output bitmap width.

OutputGranularityY

Granularity of output bitmap height.

StretchTapsX

Value indicating how well the filter can stretch the image's width. A value of 0 means the filter can't stretch; 1 means it uses pixel doubling; 2 means it uses interpolation (2 taps); 3 and higher indicate it implements better interpolation.

StretchTapsY

Value indicating how well the filter can stretch the image's height. A value of 0 means the filter can't stretch; 1 means it uses pixel doubling; 2 means it uses interpolation (2 taps); 3 and higher indicate it implements better interpolation.

ShrinkTapsX

Value indicating how well the filter can shrink the image's width. A value of 0 means the filter can't shrink; 1 means it just eliminates some rows of pixels; 2 means it uses interpolation (2 taps); 3 and higher indicate it implements better interpolation.

ShrinkTapsY

Value indicating how well the filter can shrink the image's height. A value of 0 means the filter can't shrink; 1 means it just eliminates some rows of pixels; 2 means it uses interpolation (2 taps); 3 and higher indicate it implements better interpolation.

MinFrameInterval

Minimum frame rate allowed. This applies to the capture filter only.

MaxFrameInterval

Maximum frame rate allowed. This applies to the capture filter only.

MinBitsPerSecond

Minimum data rate this pin can produce.

MaxBitsPerSecond

Maximum data rate this pin can produce.

Remarks

For example, assume the following values for some of the structure members.

• MinCroppingSize = (160, 120)
• MaxCroppingSize = (320, 240)
• CropGranularityX = 4
• CropGranularityY = 8

These values indicate that valid cropping sizes begin at MinCroppingSize and increase in steps in the x-direction by CropGranularityX and in the y-direction by CropGranularityY. In this case the x-value can be anywhere from 160 to 320 pixels in steps of 4 and the y-value can be anywhere from 120 to 240 pixels in steps of 8.

In this scenario a few of the valid sizes are:

• 160 × 120, 164 × 120, 168 × 120, 172 × 120, and so on
• 160 × 128, 164 × 128, 168 × 128, 172 × 128, and so on
• 160 × 136, 164 × 136, 168 × 136, 172 × 136, and so on

CropAlignX and CropAlignY indicate where the cropping rectangle can be inside the input size rectangle. Given a 160 × 120 sized cropping rectangle and the following:

• CropAlignX = 2
• CropAlignY = 4

Some of the valid values for the VIDEOINFOHEADER structure's rcSource member are:

• (0, 0, 160, 120)
• (2, 0, 162, 120)
• (2, 4, 162, 124)
• (2, 8, 162, 128)

For a 320 × 240 cropping rectangle and the same cropping alignment values, (2, 4, 322, 244) is one example of the many legal rectangles.

The structure members discussed in this section work together to specify what values of rcSource are valid for the VIDEOINFOHEADER structure that describes the output pin's media type. Of the remaining structure members, MinOutputSize, MaxOutputSize, OutputGranularityX, and OutputGranularityY describe the biWidth and biHeight members of the BITMAPINFOHEADER structure contained in the output pin's media type VIDEOINFOHEADER structure.

---

VIDEOINFO

Structures

Describes the bitmap and color information for a video image.

typedef struct tagVIDEOINFO {
    RECT            rcSource,
    RECT            rcTarget,
    DWORD           dwBitRate,
    DWORD           dwBitErrorRate,
    REFERENCE_TIME  AvgTimePerFrame;
    BITMAPINFOHEADER    bmiHeader;
union {
        RGBQUAD     bmiColors[iPALETTE_COLORS];
        DWORD       dwBitMasks[iMASK_COLORS];
        TRUECOLORINFO   TrueColorInfo;
    };
} VIDEOINFO;

Members

rcSource

Portion of the input video to use. See Source and Target Rectangles in Video Renderers for examples of how this member works.

rcTarget

Where the video should be displayed. See Source and Target Rectangles in Video Renderers for examples of how this member works.

dwBitRate

Approximate bit data rate.

dwBitErrorRate

Bit error rate for this stream.

AvgTimePerFrame

Average time per frame, in 100-nanosecond units.

bmiHeader

Win32 BITMAPINFOHEADER structure that contains color and dimension information for a device-independent bitmap.

bmiColors

Array of Win32 RGBQUAD structures that specifies the video's color palette. Each structure represents a single color, which is a combination of red, green, and blue intensities.

dwBitMasks

Array of DWORD values that specify true color bitmasks.

TrueColorInfo

TRUECOLORINFO structure that contains both a color palette and an array of color bitmasks.

Remarks

Never use this structure unless you are sure that you will use it only to store standard RGB formats. If you store anything other than standard RGB, the variable size of the bmiHeader structure will almost certainly cause problems. You should use the VIDEOINFOHEADER structure instead. If for some reason you find it absolutely necessary to use the VIDEOINFO structure, do not access TrueColorInfo, dwBitMasks, and bmiColors directly; use the TRUECOLORINFO, COLORS, and BITMASKS macros to return the pointers to the color information.

The first five data members are equivalent to a VIDEOINFOHEADER structure. They are expanded in full simply to reduce the amount of dereferencing needed when dealing with a pointer to a VIDEOINFO structure.

Which of the TrueColorInfo, dwBitMasks, and bmiColors fields is valid depends on the contents of the BITMAPINFOHEADER structure.

See Also

Source and Target Rectangles in Video Renderers

---

VIDEOINFOHEADER

Structures

Describes the bitmap and color information for a video image.

typedef struct tagVIDEOINFOHEADER {
    RECT                rcSource,
    RECT                rcTarget;
    DWORD               dwBitRate;
    DWORD               dwBitErrorRate;
    REFERENCE_TIME      AvgTimePerFrame;
    BITMAPINFOHEADER    bmiHeader;
} VIDEOINFOHEADER;

Members

rcSource

RECT structure that specifies the source video window. This structure can be a clipping rectangle, to select a portion of the source video stream. See Source and Target Rectangles in Video Renderers for examples of how this member works.

rcTarget

RECT structure that specifies the destination video window. See Source and Target Rectangles in Video Renderers for examples of how this member works.

dwBitRate

DWORD value that specifies the video stream's approximate data rate, in bits per second.

dwBitErrorRate

DWORD value that specifies the video stream's data error rate, in bit errors per second.

AvgTimePerFrame

REFERENCE_TIME value that specifies the video frame's average display time, in 100-nanosecond units.

bmiHeader

Win32 BITMAPINFOHEADER structure that contains color and dimension information for the video image bitmap.

See Also

Source and Target Rectangles in Video Renderers

---

VIDEOINFOHEADER2

Structures

Describes the bitmap and color information for a video image, including interlace, copy protection, and pixel aspect ratio information.

typedef struct tagVIDEOINFOHEADER2 {
    RECT                rcSource;
    RECT                rcTarget;
    DWORD               dwBitRate;
    DWORD               dwBitErrorRate;
    REFERENCE_TIME      AvgTimePerFrame;
    DWORD               dwInterlaceFlags;   // use AMINTERLACE_* defines. Reject connection if undefined bits are not 0
    DWORD               dwCopyProtectFlags; // use AMCOPYPROTECT_* defines. Reject connection if undefined bits are not 0
    DWORD               dwPictAspectRatioX; 
    DWORD               dwPictAspectRatioY; 
    DWORD               dwReserved1;        
    DWORD               dwReserved2;        
    BITMAPINFOHEADER    bmiHeader;
} VIDEOINFOHEADER2;

Members

rcSource

RECT structure that specifies what part of the source stream should be used to fill the destination buffer. The renderers can use this field to ask the decoders to stretch or clip. See Source and Target Rectangles in Video Renderers for examples of how this member works.

rcTarget

RECT structure that specifies that specifies what part of the destination buffer should be used. See Source and Target Rectangles in Video Renderers for examples of how this member works.

dwBitRate

DWORD value that specifies the video stream's approximate data rate.

dwBitErrorRate

DWORD value that specifies the video stream's data error rate.

AvgTimePerFrame

REFERENCE_TIME value that specifies the video frame's average display time, in milliseconds.

dwInterlaceFlags

Flag set by one of the following values:

Setting	Description
AMINTERLACE_IsInterlaced	Indicates an interlace stream. If 0, other interlace bits are irrelevant.
AMINTERLACE_1FieldPerSample	Indicates one field per media sample. If 0, indicates 2 fields per media sample.
AMINTERLACE_Field1First	Indicates Field 1 is first. If 0, indicates Field 2 is first. Top field in PAL is field 1, top field in NTSC is field 2.
AMINTERLACE_UNUSED	Unused.
AMINTERLACE_FieldPatternMask	Bits used to indicate field pattern.
AMINTERLACE_FieldPatField1Only	Stream never contains a Field 2.
AMINTERLACE_FieldPatField2Only	Stream never contains a Field 1.
AMINTERLACE_FieldPatBothRegular	There will be a Field 2 for every Field 1.
AMINTERLACE_FieldPatBothIrregular	Random pattern of Field 1s and Field 2s.
AMINTERLACE_DisplayModeMask	Bits used to indicate display mode.
AMINTERLACE_DisplayModeBobOnly	Indicates Bob display mode only.
AMINTERLACE_DisplayModeWeaveOnly	Indicates Weave display mode only.
AMINTERLACE_DisplayModeBobOrWeave	Indicates either Bob or Weave display mode.

Set undefined flags to zero or connection should be rejected.

dwCopyProtectFlags

Flag set with the AMCOPYPROTECT_RestrictDuplication value to indicate duplication of stream should be restricted. If undefined, specify zero or connection should be rejected.

dwPictAspectRatioX

The X dimension of picture aspect ratio, for example, 16 for 16 × 9 display (inches by inches, not pixels by pixels).

dwPictAspectRatioY

The Y dimension of picture aspect ratio, for example, 9 for 16 × 9 display (inches by inches, not pixels by pixels).

dwReserved1

Reserved for future use. Must be zero; reject connection otherwise

dwReserved2

Reserved for future use. Must be zero; reject connection otherwise

bmiHeader

Win32 BITMAPINFOHEADER structure that contains color and dimension information for the video image bitmap.

See Also

Source and Target Rectangles in Video Renderers

---

REGPINTYPES

Structures

Contains media type information for registering a filter.

typedef struct
{
    const CLSID * clsMajorType;
    const CLSID * clsMinorType;
} REGPINTYPES;

Members

clsMajorType

Major media type supported by the filter.

clsMinorType

Minor media type supported by the filter.

Remarks

This structure is used by the IFilterMapper and IFilterMapper2 interfaces to identify media types a pin handles and to register filters.

This structure is equivalent to the AMOVIESETUP_MEDIATYPE structure.

---

REGFILTERPINS

Structures

Contains pin information for registering a filter.

typedef struct
{
    LPWSTR           strName;
    BOOL             bRendered;
    BOOL             bOutput;
    BOOL             bZero;
    BOOL             bMany;
    const CLSID *    clsConnectsToFilter;
    const WCHAR *    strConnectsToPin;
    UINT             nMediaTypes;
    const REGPINTYPES * lpMediaType;
} REGFILTERPINS;

Members

strName

Name of the pin.

bRendered

Set to TRUE if the filter renders this input; otherwise, set to FALSE.

bOutput

Set to TRUE if this pin is an output pin.

bZero

Set to TRUE if the filter has zero instances of this pin; otherwise, set to FALSE.

bMany

Set to TRUE if the filter has more than one instance of this pin; otherwise, set to FALSE.

clsConnectsToFilter

CLSID of the filter to which this filter connects in a filter graph.

strConnectsToPin

Name of the pin to which this pin connects in a filter graph.

nMediaTypes

Number of media types supported by this pin.

lpMediaType

REGPINTYPES structure providing media type information.

Remarks

This structure is used by the IFilterMapper and IFilterMapper2 interfaces for filter registration. It is used if the dwVersion member in REGFILTER2 is 1.

This structure is equivalent to the AMOVIESETUP_PIN structure.

---

REGPINMEDIUM

Structures

Describes a pin medium (as defined in the Windows NT DDK) for registration through the IFilterMapper2 interface.

typedef struct
{
    CLSID clsMedium;
    DWORD dw1;
    DWORD dw2;
} REGPINMEDIUM;

Members

clsMedium

Contains the globally unique set identifier.

dw1

Contains the set-specific identifier for an item within the set.

dw2

Used for various set flags. Zero when not used.

Remarks

A medium defines a method of communication (for example, the bus over which the communication occurs). Each ID within that set is used to represent the form of communication. Register mediums for your filter if you need to search for DirectShow filters built on kernel streaming pins, which can connect to each other.

---

REGFILTERPINS2

Structures

Contains information for registering a filter through the IFilterMapper2 interface.

typedef struct
{    
    DWORD dwFlags;
    UINT             cInstances;
    UINT             nMediaTypes;
    [size_is(nMediaTypes)] const REGPINTYPES * lpMediaType;
    UINT             nMediums;
    [size_is(nMediums)] const REGPINMEDIUM *lpMedium;
    const CLSID      *clsPinCategory;
} REGFILTERPINS2;

Members

dwFlags

Combination of REG_PINFLAG flags.

cInstances

Number of instances of the pin, if known.

nMediaTypes

Number of media types supported by this pin.

lpMediaType

Array of nMediaTypes REGPINTYPES structures providing media type information.

nMediums

Number of mediums.

lpMedium

Array of REGPINMEDIUM structures containing medium information for each pin.

clsPinCategory

Pin category (for kernel streaming pins) as defined in the Windows NT DDK.

---

REGFILTER2

Structures

Describes a filter for registration through the IFilterMapper2 interface.

typedef struct
{
    DWORD dwVersion;            // 1 or 2
    DWORD dwMerit;

    /* unnamed union */
    [switch_is(dwVersion)] [switch_type(DWORD)] union
    {
        [case(1)]

            struct
            {
                ULONG cPins;
                [size_is(cPins)] const REGFILTERPINS *rgPins;
            };

        [case(2)]

            struct
            {
                ULONG cPins2;
                [size_is(cPins2)] const REGFILTERPINS2 *rgPins2;
            };

        [default]
            ;
    } ;

} REGFILTER2;

Members

dwVersion

Indicates the filter registration format to use.

dwMerit

Position in the order of enumeration. Filters or categories with higher merit are enumerated first.

cPins

Number of pins (if dwVersion = 1).

rgPins

Array of REGFILTERPINS structures representing each pin to be registered (if dwVersion = 1).

cPins2

Number of pins (if dwVersion = 2).

rgPins2

Array of REGFILTERPINS2 structures representing each pin to be registered (if dwVersion = 2).

Remarks

This structure is passed in to the IFilterMapper2::RegisterFilter method.

Set dwVersion to 1 if you are using the old format, or to 2 if you need mediums and pin categories.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page