Microsoft DirectX 8.0

Working with Sources

A source object represents a single media stream from a source file. Sources provide the raw material for a project. Everything else in the timeline exists either to provide structure (tracks, compositions, and groups) or to modify sources (effects and transitions).

This article describes various details relating to sources in Microsoft® DirectShow® Editing Services (DES). For information on the basic steps needed to add a source to the timeline, see Constructing a Timeline.

This article contains the following sections.

Setting Properties on Sources

When you create a new source object, there are a few properties you are required to set and others you can optionally set. You must set the following properties.

A source object inherits its media type from the parent group, so it is not necessary to specify a media type.

Optional properties include the following:

Using the Media Detector

The media detector is a helper object that can retrieve information about a file, such as the number of streams, their type, and their duration. It also contains methods for retrieving poster frames from a video stream. It exposes the IMediaDet interface.

The media detector operates in one of two modes. When you create an instance of the media detector, it is not attached to a particular source file. In this mode, you can retrieve stream information from multiple source files. However, once you use the media detector to obtain a poster frame, it switches to bitmap grab mode. In bitmap grab mode, the media detector is attached to a specific video stream, and the stream information methods no longer work. Moreover, there is no way to switch the media detector back to its starting mode. Therefore, obtain any stream information you need before retrieving poster frames, or else create new instances of the media detector for each stream.

To obtain stream information, do the following:

  1. Call IMediaDet::put_Filename with the name of the source file.
  2. Call IMediaDet::get_OutputStreams to obtain the number of streams in the source.
  3. Specify a stream number with IMediaDet::put_CurrentStream. Then call one or more of the following methods:

To obtain a poster frame, specify the stream number, as in the previous step. Then call either IMediaDet::GetBitmapBits, which copies a poster frame into a buffer, or IMediaDet::WriteBitmapBits, which saves a poster frame to a file.

Using the Media Locator

The media locator is a helper object that verifies file names and searches for missing files on local or network directories. The media detector keeps a cache of directory paths where it has successfully found files in past searches. To locate a file, it searches the directories in its cache. Failing that, the media detector can display an Open File dialog for the user to locate a file manually. Assuming the user locates the file, the media locator adds the new directory to its cache. The media locator exposes the IMediaLocator interface.

Typically, your application does not directly create an instance of the media locator. Instead, the timeline and the render engine provide the following methods for validating file names using the media detector.

Both methods take flags that control the behavior of the media locator. For example, you can restrict the search to local directories.

Still Images

DES supports the following file formats for still images:

They can be used either as still images, or to create animations. For bitmap, JPEG, and Targa files, if you are using the file as a still image, call the IAMTimelineSrc::SetDefaultFPS method to set the frame rate to zero.

DIB Sequences

Given a series of bitmap, JPEG, or Targa files, the render engine can construct a device-independent bitmap (DIB) sequence. To create a DIB sequence, give the files numerically sequential names, such as Image001.bmp, Image002.bmp, Image003.bmp, and so on. Use the first file in the sequence as the source. Set the frame rate for the sequence by calling IAMTimelineSrc::SetDefaultFPS. The render engine cycles through the images in the sequence at the specified frame rate.

If the sequence is too short to fill the duration, given the frame rate, the rest of the duration is solid black. No error occurs during rendering.

GIF Sources

DES supports GIF sources, including animated and transparent GIFs, using the GIF89a specification. With an animated GIF, unlike the other file types, you do not need to set the frame rate. The GIF file specifies the delay between each image in the animation.

To support transparent GIFs, DES converts transparent regions in the image to the RGB triplet RGB(0,0,0). You can then use the Key Transition to key on RGB(0,0,0).

DES also converts any black regions that fall within the range RGB(0–7,0–7,0–7) to the value RGB(8,8,8)—except for the transparency index, if it falls in that range. This conversion is not detectable to the eye.

Video Color Source

The Video Color Source object creates a continuous video image of a solid color. One use for this object is to make it a layer in a transition. For example, you could use it to create a video fade-in or fade-out.