Share via

Implementing Render

  • Article

[The feature associated with this page, Windows Media Player SDK, is a legacy feature. It has been superseded by MediaPlayer. MediaPlayer has been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer instead of Windows Media Player SDK, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The easiest way to think of visualization programming is that you are creating a handler for a timed event. At specific intervals, Windows Media Player takes a snapshot of the audio data it is playing, and provides the snapshot data to the currently loaded visualization. This is similar to event-driven programming and is part of the programming model of Microsoft Windows. You write code and wait for it to be called by a particular event.

If your code is an implementation of the IWMPEffects::Render function for rendering in windowless mode, it receives the following parameters:

TimedLevel

This is a structure that defines the audio data your code will be analyzing. The structure is composed of two arrays. The first array is based on frequency information and contains a snapshot of the audio spectrum divided into 1024 portions. Each cell of the array contains a value from 0 to 255. The first cell starts at 20 Hz and the last at 22050 Hz. The array is two dimensional to represent stereo audio. The second array is based on waveform information and corresponds to audio power, where the stronger the wave is, the larger the value. The waveform array is a granular snapshot of the last 1024 slices of audio power taken at very small time intervals. This array also is two dimensional to represent stereo audio.

HDC

This is a Microsoft Windows handle to a device context. This gives a way to identify the drawing surface to Windows. You do not need to create it, you just need to use it for specific drawing function calls.

RECT

This is a Microsoft Windows rectangle that defines the size of a drawing surface. This is a simple rectangle with four properties: left, right, top, and bottom. The actual values are supplied by Windows Media Player so that you can determine how the user or skin developer has sized the window you will draw on. It also determines the position on the HDC that the effect is supposed to render on.

If your code is an implementation of the IWMPEffects2::RenderWindowed function for rendering in a window, it receives the following parameters:

TimedLevel

This is the same information that the Render function receives.

fRequiredRender

The fRequiredRender parameter informs you that your visualization must repaint itself—for example, when another window is dragged over it. When this value is false, you can safely skip over the rendering code if the current media item is stopped or paused. This lets you avoid consuming CPU cycles unnecessarily.

The sample plug-in generated by the Plug-in Wizard does not provide a custom implementation for RenderWindowed. Instead, the sample plug-in code retrieves the device context from the parent window provided by Windows Media Player in IWMPEffects2::Create, then retrieves the dimensions of the parent window as a RECT structure, and then calls through to Render using the device context, the RECT, and the timed level pointer from RenderWindowed.

The following sections provide more information about implementing Render:

Implementing Your Code