## 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
  Bit to use.
rcTarget
  Where the video should be displayed.
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.

###

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.
rcTarget
  RECT structure that specifies the destination video window.
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.

###

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.
rcTarget
  RECT structure that specifies that specifies what part of the destination buffer should be used.
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.

###

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.

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