tagKS_FRAME_INFO structure

The KS_FRAME_INFO structure extends the KSSTREAM_HEADER structure for video streams.

Syntax

typedef struct tagKS_FRAME_INFO {
  ULONG    ExtendedHeaderSize;
  DWORD    dwFrameFlags;
  LONGLONG PictureNumber;
  LONGLONG DropCount;
  HANDLE   hDirectDraw;
  HANDLE   hSurfaceHandle;
  RECT     DirectDrawRect;
  union {
    LONG  lSurfacePitch;
    DWORD Reserved1;
  };
  DWORD    Reserved2;
  union {
    struct {
      DWORD Reserved3;
      DWORD Reserved4;
    };
    ULONGLONG FrameCompletionNumber;
  };
} KS_FRAME_INFO, *PKS_FRAME_INFO;

Members

DirectDrawRect

Specifies the portion of the DirectDraw surface that has been locked. This is normally the entire surface.

DropCount

Specifies the number of pictures that were not captured. During capture, the minidriver sets this member. This counter should be incremented whenever a frame should have been captured but was not; this condition usually arises when no buffers were available during capture. Initialize or update this value on transition into KSSTATE_ACQUIRE.

dwFrameFlags

Specifies flags indicating additional information about the frame captured. During capture, the minidriver sets this member to one of the following values that are defined in ksmedia.h:

Flag Meaning
KS_VIDEO_FLAG_FRAME Indicates a complete frame.
KS_VIDEO_FLAG_FIELD1 Indicates Field 1 of a two-field sequence.
KS_VIDEO_FLAG_FIELD2 Indicates Field 2 of a two-field sequence.
KS_VIDEO_FLAG_I_FRAME Indicates that this frame can be completely decoded without reference to any other frames.
KS_VIDEO_FLAG_P_FRAME Indicates that this is a predicted frame.
KS_VIDEO_FLAG_B_FRAME Indicates that this is a bidirectional frame.

ExtendedHeaderSize

Specifies the size of this structure, in bytes.

hDirectDraw

Specifies the user-mode handle to DirectDraw. This handle is only provided to the minidriver when capturing to a DirectDraw surface for preview or overlay purposes.

hSurfaceHandle

Specifies the user-mode handle to the DirectDraw surface. This handle is only provided to the minidriver when capturing to a DirectDraw surface for preview or overlay purposes.

PictureNumber

Specifies a count representing the current picture number. Initialize or update this value on transition into KSSTATE_ACQUIRE.

Reserved2

Reserved and should not be used by the minidriver.

Remarks

The KS_FRAME_INFO structure provides a way to return information about the frame captured, as well as a way to pass Microsoft DirectDraw handles used when capturing to a DirectDraw surface.

The PictureNumber member count represents the count of the current picture, which is calculated in one of two ways depending on the device:

  • Measure the time since the stream was started and divide by the frame duration. This method is appropriate for devices that do not provide their own clock. For example:

    PictureNumber = ElapsedTime / FrameDuration;

  • Add together the count of frames captured and the count of frame dropped. This method is appropriate for devices that provide their own clock. For example:

    PictureNumber = FramesCaptured + FramesDropped;

When calculating PictureNumber and DropCount, it is important to use the frame duration specified when the stream was opened, which may not necessarily match the rate at which the device is actually producing images. For example, a USB camera may only produce images at 7.5 fps, but a client could open the stream at 8 fps. In this case, all calculations should use the 8 fps number.

For more information about updating PictureNumber and DropCount see Capturing Video.

Requirements

   
Header ksmedia.h (include Ksmedia.h)

See Also

KSSTREAM_HEADER

Send comments about this topic to Microsoft