Appendix A: Interface List

IMPAVisualization


Purpose	Used to create visualization component for RealJukebox and RealPlayer
Header file	`impavisualization.h`

The IMPAVisualization interface contains the following methods:


IMPAVisualizationPlugin::InitPlugin


IMPAVisualizationPlugin::GetPluginInfo


IMPAVisualizationPlugin::GetPluginProperties


IMPAVisualizationPlugin::SetPreferences


IMPAVisualizationPlugin::Configure


IMPAVisualizationPlugin::SetRender


IMPAVisualizationPlugin::OnDrawBuffer


IMPAVisualizationPlugin::OnClick


IMPAVisualizationPlugin::SetWindow


IMPAVisualizationPlugin::OnDrawWindow

As with all COM interfaces, the IMPAVisualization interface inherits the following IUnknown methods:


IUnknown::AddRef


IUnknown::QueryInterface


IUnknown::Release

IMPAVisualizationPlugin::InitPlugin

Called with a context that the plug-in can use to perform a QueryInterface() for interfaces supported by the application.


STDMETHOD(InitPlugin)  (
      THIS_ 
      IUnknown* pContext
) PURE;

pContext: Pointer to the context.

IMPAVisualizationPlugin::GetPluginInfo

Called to get name, creator, and description information from the plug-in. All strings returned must contain no more than 256 characters.


STDMETHOD(GetPluginInfo)  (
      THIS_ 
       char* szName, char* szCreator, char* szDescription
) PURE;

szName: The name of the plug-in.
szCreator: Author of the plug-in.
szDescription: Description of the plug-in.

IMPAVisualizationPlugin::GetPluginProperties

Called to get information about the visualization effects supported and whether the plug-in wants spectral audio data. The IRMAValues pExtendedParams passed in are used for extending the properties that can be supported.

The extended parameters are:

VIZ_RENDER_MODE, which defines the rendering mode the plug-in uses. Valid values are VIZ_RENDER_BUFFER and VIZ_RENDER_WINDOW. The default value is VIZ_RENDER_BUFFER.
VIZ_SUPPORT_CONFIGURE, which the plug-in uses when it supports the new configuration feature. Valid values are 0 (false) or 1( true). The default value is 0.


STDMETHOD(GetPluginProperties)  (
      THIS_ UINT32* pnEffectsFlags, bool* pbWantSpectrum, 
      IRMAValues* pExtendedParams) 
) PURE;

pnEffectsFlags: Lists the visualization effects that are supported.
pbWantSpectrum: Tells whether the plug-in should receive spectral audio data.
pExtendedParams: Lists the plug-in properties that are supported.

IMPAVisualizationPlugin::SetPreferences

Passes a preferences interface to the plug-in. The plug-in can use this preferences interface to store its own settings. Use ReadPref and WritePref to get and set settings for your plug-in.


STDMETHOD(SetPreferences)  (
      THIS_ IRMAPreferences* pPrefs
) PURE;

pPrefs: Pointer to the preferences interface.

IMPAVisualizationPlugin::Configure

Allows the plug-in to display its own configuration dialog if SupportsConfigure has been returned. You can cast pParent->window to an HWND to use as your parent window. Your dialog should be modal.


STDMETHOD(Configure)  (
      THIS_ PNxWindow* pParent) 
PURE;

pParent: Pointer to the parent window.

IMPAVisualizationPlugin::SetRender

Tells the plug-in that it is going to be actively used for rendering, that is, that music is playing.


STDMETHOD(SetRender)  (
      THIS_ BOOL bRender
) PURE;

bRender: Tells the plug-in whether it is going to be actively used for rendering. When SetRender is called with bRender set to false, the window should be cleared, or reset to a default image if in VIZ_RENDER_WINDOW mode. The initial render mode should always be false.

IMPAVisualizationPlugin::OnDrawBuffer

Tells the plug-in to draw into the passed-in video buffer if the render mode is set to VIZ_RENDER_BUFFER.


STDMETHOD(OnDrawBuffer)  (
      THIS_ unsigned char* pVideoBuffer, int width, int height, 
      int pitch, int bitsperpixel, MPAVizAudioData* pAudioData
) PURE;

pVideoBuffer: Points to the beginning of the buffer.
width: Width, in pixels, of the visualization.
height: Height, in pixels, of the visualization.
pitch: Pitch, in bytes per row, of the visualization. A negative value for pitch means that this is a bottom-up DIB, with the origin in the lower-left corner. Currently, pitch is always negative.
bitsperpixel: Currently, the value of bitsperpixel is always 32. Do not draw outside the lines. Possible future support for extended parameters may allow the plug-in to indicate support for more RGB formats, for example, 24-bit or 16-bit color.
pAudioData: Pointer to audio data.

IMPAVisualizationPlugin::OnClick

Informs the plug-in that a click has occurred on the plug-in.


STDMETHOD(OnClick) (
     THIS_ int x, int y, int keys
) PURE;

x: x-coordinate of the location of the click.
y: y-coordinate of the location of the click.
keys: Any combination of the following values defined by Windows:

IMPAVisualizationPlugin::SetWindow

Gives a window handle to the plug-in. The user can subclass the window handle to receive messages on size or hiding and showing. Any window created to handle drawing should not draw outside the area of this window, and this window should be the parent in order to maintain z-order.

The benefit of creating a child window is that when the visualization engine passes a new window to the plug-in, you can reset the parent of the window. For example, assume that the passed-in window is valid until SetWindow is called, where pWindow->window points to a different window, or to NULL. (NULL means no window.) When SetWindow is called with a new window, be sure to unsubclass the previous window passed in, and remove any child windows you previously added to that window.

Note
The only value you should use in the PNxWindow structure is pWindow->window.On Windows, you can cast that void* to HWND.

	Note
The only value you should use in the `PNxWindow` structure is `pWindow->window.`On Windows, you can cast that `void*` to `HWND`.


STDMETHOD(SetWindow)  (
      THIS_ PNxWindow* pWindow
) PURE;

pWindow: Pointer to the window handle.

IMPAVisualizationPlugin::OnDrawWindow

Tells the plug-in to draw into its window if the render mode is set to VIZ_RENDER_WINDOW.

Note
The only value you should use in the PNxWindow structure is pWindow->window. On Windows, you can cast that void* to HWND.

	Note
The only value you should use in the `PNxWindow` structure is `pWindow->window.` On Windows, you can cast that `void*` to `HWND`.


STDMETHOD(OnDrawWindow)  (
      THIS_ PNxWindow* pWindow, MPAVizAudioData* pAudioData
) PURE;

pWindow: Pointer to the window that was last passed in to the SetWindow call. You can ignore the pointer, although you may choose to check and verify its contents.
pAudioData: Pointer to audio data.