Chapter 3: The Visualization Interface

This chapter explains how RealJukebox and a visualization plug-in use the visualization interface. The sample code included with this SDK illustrates many of the features described here. You can use the sample code as a starting point for building your own plug-in.

Using the Visualization Interface

Every visualization plug-in implements the IMPAVisualizationPlugin interface (as defined in impavisualization.h). This interface creates the visualization.

Before you begin, make copies of the sample files included in this kit.

To create a visualization plug-in:

Update the SampleVisualizationPlugin.rc2 file, which contains the version information for your plug-in.
Be sure you export the MPACreateVisualization function.
Name the DLL with the .rpv extension.
Copy the .rpv file to the C:\Program Files\Common Files\Real\Visualizations folder. Because RealJukebox regularly checks this directory, you can copy the file to this directory while RealJukebox is running.

Buffer Mode Rendering

Buffer mode rendering uses the following methods:

CSampleVisualPlugin::Clicked. Add code if you want mouse-click support, which notifies you when the visualization is being clicked on and is reacting to the click. In some modes in the RealJukebox application, you may not receive clicks when your visualization is being shown.

CSampleVisualPlugin::OnDrawBuffer. Add your plug-in rendering code here.

Note
A 32-bit RGB video pointer is provided with the API. The API is set up for possible future support of additional color formats, depending on the screen resolution or other conditions. The video pointer points to the beginning of the buffer. In bottom-up DIBs, the first row is actually near the end of the buffer. Width and height are in pixels. Pitch is in number of bytes per row, and is negative because this is a bottom-up DIB.

	Note
A 32-bit RGB video pointer is provided with the API. The API is set up for possible future support of additional color formats, depending on the screen resolution or other conditions. The video pointer points to the beginning of the buffer. In bottom-up DIBs, the first row is actually near the end of the buffer. Width and height are in pixels. Pitch is in number of bytes per row, and is negative because this is a bottom-up DIB.

You can render into a different buffer, such as a DC using Windows or OpenGL functions, and then copy the bits back into the passed-in buffer if you want to use different APIs than those used for direct rendering. However, be aware that the additional memcpy operation can be detrimental to visualization performance.

Window Mode Rendering

Window mode rendering uses the following methods:

CSampleVisualPlugin::GetPluginProperties. To set up window mode, set the extended parameter VIZ_RENDER_MODE to the setting VIZ_RENDER_WINDOW in the GetPluginProperties function.
CSampleVisualPlugin::SetWindow. When the visualization window is set, you are called with SetWindow. You can subclass the window, but you must remember to unsubclass the window when SetWindow is called with a different window handle or with a NULL window handle. SetWindow is called with a NULL window handle when your plug-in is supposed to get rid of the windows and is going away. When RealJukebox changes from docked to undocked visualizations, SetWindow is called with a different window. You may be better off creating a child window and using SetParent when you get different windows from RealJukebox, instead of subclassing and handling the painting as shown in the example in this document.
CSampleVisualPlugin:OnDrawWindow. OnDrawWindow is called with the window handle, which should be the same handle you received in SetWindow, and the audio data. You should do all data processing on the audio data in this function call, not on your window thread. You should perform as much window manipulation as possible on the window thread by sending or posting messages to the window, rather than in response to OnDrawWindow calls directly. OnDrawWindow is not called from the same thread that creates the window, which is the thread where your WindowProc is called.