Transform Filters

This article details sample transform filters (sometimes called effects). The sample transform filters include an audio effect, some video effects, some MPEG codecs, a VCR controller, and various "null" (pass-through) filters.

This article contains the following sections.

Contrast Sample (Video Contrast Filter)
EzRGB24 Sample (Image Effect Filter)
Gargle Sample (Gargle Filter)
Inftee Sample (Infinite-Pin Tee Filter)
MPGAudio Sample (MPEG Audio Decoder Filter)
MPGVideo Sample (MPEG Video Decoder Filter)
Nullip Sample (Null In-Place Filter)
Nullnull Sample (Minimal Null Filter)
Vcrctrl Sample (VCR Control Filter)
WavDest Sample (WavDest Filter)

Contrast Sample (Video Contrast Filter)

The video contrast sample filter, Contrast, illustrates how to define and implement a simple custom interface within the structure provided by the Microsoft® DirectShow® base classes. This filter demonstrates how to use the CTransformFilter class to implement a simple effect filter.

The Contrast filter also provides a good example of the flexibility of the filter graph architecture. This flexibility is demonstrated when the filter is used in conjunction with a tee filter to produce "before and after" (side-by-side original and modified) video streams.

The Contrast filter is a simple transform filter that adjusts the contrast of the video stream that is passed through it. It provides a custom interface for adjusting the contrast. The Contrast filter also uses the CBasePropertyPage class to provide a property page for applications that do not provide a user interface.

Note The Contrast filter adjusts the contrast by using a trick with palettes. The color palette of an image effectively determines how the image is interpreted. By changing the palette, the filter can change the contrast without changing the image pixels themselves.

This filter is installed with the DirectShow run time and is available through the Filter Graph Editor when you choose Insert Filters from the Graph menu, and select the DirectShow Filters category.

Sample Locations

EzRGB24 Sample (Image Effect Filter)

The RGB 24 image effect filter, EzRGB24, is a sample of an image processing filter. This shows usage of a number of DirectShow classes and interfaces, including CTransformFilter, CPersistStream, CBasePropertyPage, and ISpecifyPropertyPages.

This filter's purpose is to provide fast and single stream effects. The EzRGB24 filter also shows how to add image processing effects using DirectShow. You can use this filter as a component of an DirectShow video editor. Effects with fast execution were selected to help demonstrate the power of DirectShow in enabling real-time effects—the idea was to show something that could not have been built by using Microsoft Video for Windows®.

This filter performs a number of individual video effects. These include red, green, blue, darken, XOR, blur, gray, and emboss image-processing effects.

Sample Locations

Gargle Sample (Gargle Filter)

The audio processing filter, Gargle, illustrates how to create a simple sound effect. More sophisticated effects such as echo, flanging, band-pass filtering, and other effects can be created in a way similar to that demonstrated by the Gargle filter. This sample demonstrates the CTransInPlaceFilter, CPersistStream, and CBasePropertyPage classes. It also shows use of the ASSERT, DbgBreak, DbgLog, and DbgBreakPoint debug macros.

The Gargle filter modulates the waveform passing through it by multiplying the waveform by another waveform that is mathematically generated within the filter. The modulating waveform is, by default, a triangular wave. The property sheet also offers the alternative of a square wave. You can set the frequency of the modulating wave through the filter's property sheet. At low frequencies (near 1 Hz), the sound grows and diminishes. At medium frequencies (5 to 15 Hz), the sound has a tremolo quality, which is why it is referred to as gargling. At higher frequencies (100 Hz and up), the filter generates extra frequencies in the original sound. If a 500 hertz (Hz) sound is played at 100 Hz, then it produces additional frequencies of 400 Hz, 600 Hz, 200 Hz, 800 Hz, and so on.

Sample Locations

Inftee Sample (Infinite-Pin Tee Filter)

The Inftee sample infinite-pin tee filter has multiple output pins and passes through type enumerators from source filters. The filter uses the CAutoLock, CBaseFilter, CBaseInputPin, CBaseOutputPin, CCritSec, and COutputQueue base classes.

Inftee has one input pin and a variable number of output pins, typically two. It accepts data samples through the IMemInputPin transport, which it implements. All data samples sent to the filter are delivered down all paths simultaneously, therefore teeing the input into multiple separate output streams. The data samples are not type-specific, so the input, for example, can be text lyrics, video images, or audio buffers.

When considering two output pins, the tee filter sends the same data down both of the pins; therefore, the pins must have negotiated the same media type during connection. The infinite-pin tee filter handles this negotiation so that the input pin and both output pins converge when using the same media type. If a suitable media type cannot be found, then the connection is rejected.

The filter always uses the suggested allocator; the filter that provides the data suggests the allocator. The data arriving at the input pin is not copied before it is sent to the output pins. The filter also ensures that the data is delivered to the downstream filters, to guarantee that both outputs receive timely service. In particular, if one of the outputs can block in the COutputQueue::Receive member function, then the tee spins off a thread to deliver the sample. If there were no thread to deliver the sample, then the thread that delivers the sample to the tee input pin might pass the data to a downstream filter; at that point, it might block, keeping data from the other downstream filter for long periods of time.

Sample Locations

MPGAudio Sample (MPEG Audio Decoder Filter)

The sample MPEG audio codec, MPGAudio, provides a prototype for an MPEG audio decoder. It uses the CTransformFilter class.

As supplied, this framework just consumes the passed-in audio frames. That is, audio frames do not produce any output from this framework. You would need to expand the framework with code specific to the outputs desired.

Sample Locations

MPGVideo Sample (MPEG Video Decoder Filter)

The sample MPEG video codec, MPGVideo, provides a prototype for an MPEG video decoder. It uses the CTransformFilter class. The MPGVideo filter also shows the processing of quality-management messages.

As supplied, this framework just consumes the passed-in video frames. That is, video frames do not produce any output from this framework. You would need to expand the framework with code specific to the outputs desired.

Sample Locations

Nullip Sample (Null In-Place Filter)

The null in-place sample filter, Nullip, is an example of a transform-inplace filter. It illustrates how a transform filter can behave in a relatively transparent manner. Nullip is a simple filter that passes all data from its input pin to its output pin. No transformations are performed on the data.

The Nullip filter provides an example of using the CTransInPlaceInputPin class. It shows how to use the CAutoLock class to automatically release critical sections. Other classes used include CTransInPlaceFilter, CBasePropertyPage, CMediaType, and CTransInPlaceOutputPin. It also enables a user to select the media types that it can pass through itself. This filter has one input pin, one output pin, and performs its transform in place (without copying the data) in the push thread. In other words, the CTransInPlaceFilter::Receive method is called with a buffer, which it transforms and delivers to the next filter downstream. The Receive method is then blocked until that filter returns; it subsequently returns to its own calling member function.

Sample Locations

Nullnull Sample (Minimal Null Filter)

The minimal null sample filter, Nullnull, illustrates a minimal filter. It does not support the media type selection that Nullip does. The Nullnull filter uses the CTransInPlaceFilter class.

Sample Locations

Vcrctrl Sample (VCR Control Filter)

The VCR control sample filter, Vcrctrl, is a simple implementation of the external device control interfaces that DirectShow provides. Vcrctrl provides basic transport control and SMPTE timecode-reading capabilities for certain Betacam and SVHS videocassette recorders with RS-422 or RS-232 serial interfaces (see source code for specific machine types supported).

This sample is not intended to be a frame-accurate, system-ready implementation ready for professional applications. It is designed to show basic device control filter structure, and therefore does not implement several of the more sophisticated features of the interfaces, such as edit event control. Frame-accurate control is best achieved by writing a low-level, kernel-mode communications driver underneath the filter. Developers should refer to the Driver Development Kit (DDK) for the appropriate platform.

Using the Sample

With this sample, you can control a VCR through property pages. You should keep in mind the following points.

The sample automatically links the transport to the graph's Run, Pause, and Stop methods. You can unlink the transport on the General property page by removing the selection from the Link to Graph check box. This is a persistent property, so if you save the graph the transport will remain unlinked.
The filter automatically detects the presence of a compatible VCR on COM2. If it can't find a VCR or if the port is in use, it switches to simulation mode. You can select the port to use on the General property page.
The timecode pin can connect either to the text renderer or the timecode renderer (Tcrender.ax), which accepts the media type MEDIATYPE_AuxData/MEDIASUBTYPE_Timecode.
The main property page shows the available video and audio inputs, although you can't select them. The hardware does not support this feature, and it was implemented to show physical pin property enumeration.
The device communications class (CDevCom, specified in Cdevcom.h and Cdevcom.cpp) is thread-safe and handles SMPTE timecodes. On some VCRs, timecode detection is not supported, so timecode values might not be accurate.

Advanced Topic: Event Notification

There are certain situations where a device control filter must asynchronously notify the application of things such as availability of a "freshly read" timecode value, or completion of some time-consuming operation such as rewinding a tape back to the beginning. The VCR control sample filter demonstrates the use of the DirectShow event notification mechanism to signal timecode availability. For additional information, see the documentation on IMediaEvent and the Handling Events topic in the "Controlling Filter Graphs Using C" overview article.

This sample contains the following files.

Vcrutil.h, .cpp—implementation of the device control interfaces
Fvcrctrl.h, .cpp—the filter implementation
Cdevcom.h, .cpp—the communications object that handles device-specific protocols and the serial port interface
Ctimecod.h, .cpp—the SMPTE timecode support
Trprop.h, .cpp—the transport properties
Vcrprop.h, .cpp—the general properties
Vcrprop.rc—the dialog resources
Vcrctrl.def—the module definition file
Vcruids.h—the CLSIDs used by the filter

Sample Locations

WavDest Sample (WavDest Filter)

The WavDest sample filter is used to write an audio stream to a WAV file. It takes a single audio stream as input, and its output pin should be connected to the File Writer filter. This sample filter is based on the CTransformFilter class.

To use the filter, create a filter graph with an audio stream connected to the WavDest filter's input pin and the File Writer filter connected to the WavDest filter's output pin. When you run the filter graph, a WAV-formatted file will be written.

Sample Locations