Chapter 2: Development Framework

This chapter explains how the Real Visualization SDK implements COM, and provides instructions for compiling the sample plug-in that is included with the SDK.

How the Real Visualization SDK Differs from COM

RealSystem components use the COM QueryInterface() method to expose their interfaces. The Real Visualization COM-style interfaces begin with the prefix IMPA, which stands for Interface Music Platform Architecture.

Although the Real Visualization SDK architecture is based on the COM standard, the SDK does not use all aspects of COM. Instead, it implements a subset of COM functions to provide cross-platform operation without requiring Windows libraries or Windows emulation code on UNIX and Macintosh platforms. The Real Visualization SDK thus eliminates the need for storage-intensive Windows components such as the registry and the COM and OLE runtime libraries. The following sections describe how the Real Visualization SDK diverges from the COM standard.

	Additional Information
	Visit http://www.microsoft.com/com/default.asp for more information on COM.

Creating a Plug-In Instance

The Real Visualization SDK does not use the Windows CoCreateInstance() method to create plug-in objects. Instead, each visualization plug-in implements MPACreateVisualization(), a C-style entry. The following extract from a Real Visualization SDK sample file illustrates the entry point.

/* Exported Entry Point - Create Function */
PN_RESULT DLLEXP MPACreateVisualization(IUnknown** ppIUnknown)
{
     // Create a new instance of a visualization plug-in...
     *ppIUnknown = (IUnknown*)new CSampleVisualPlugin();
      if (*ppIUnknown)
     {
          (*ppIUnknown)->AddRef();
          return PNR_OK;
     }
     // Out of memory
     return PNR_OUTOFMEMORY;
}

Creating a RealSystem Object

The Real Visualization SDK uses RealSystem interfaces. RealSystem COM-style interfaces begin with the prefix IMPA, which stands for Interface Music Platform Architecture, or IRMA, which stands for Interface RealMedia Architecture. A RealSystem component can use the C++ new operator to create objects that it alone manipulates. However, to create objects passed to other RealSystem components, a component should use IRMACommonClassFactory. When RealSystem initializes a component, it passes to the component a pointer to the system context. The component can then use this pointer to call IRMACommonClassFactory::CreateInstance() and create new RealSystem objects. The following extract from a RealSystem SDK sample file illustrates the function call.

m_pClassFactory-CreateInstance(CLSID_IRMABuffer, (void**)&pStringObj);

Using AddRef() and Release()

Because RealSystem objects are often utilized by other RealSystem objects, objects must correctly implement reference counting. The COM functions AddRef() and Release() control reference counting and therefore determine the lifetime of each object. The following rules describe the requirements for RealSystem components' use of AddRef() and Release() with objects.

• The following functions perform an AddRef() on objects before returning them. When a component finishes using the object, it must Release() the object.

  • MPACreateVisualization()

  • IUnknown::QueryInterface()

• If a component receives an object as a parameter of a function call, the component must perform an AddRef() on the object. When the component finishes using the object, it must Release() the object.

• If a component uses the C++ new operator to create an object, the component must perform an AddRef() on the object and then Release() the object when finished.

Suggestions for Designing a Plug-In

Keep the following general suggestions in mind as you develop plug-ins.

• Keep your plug-ins as simple, self-contained, and universal as possible.

• Consider the impact of the plug-in on other functions in RealJukebox and RealPlayer.

Compiling a Plug-In

The Real Visualization SDK includes two sample plug-ins that you can use as a basis for creating plug-ins.

• The BufferMode sample source code demonstrates how to create a visualization plug-in that renders the graphic in a buffer that is then rendered by the application, either RealJukebox or RealPlayer, in the visualization window pane.

• The WindowMode sample source code demonstrates how to render graphical data directly into a window pane.

Building the Sample Plug-In

Before you build your plug-in, you should test-compile the sample files. On Windows, RealNetworks recommends using Microsoft Visual C++ 4.2 or 6.0.

	Additional Information
	Visit http://www.microsoft.com/products for more information on Microsoft Visual C++.

A Microsoft Developer Studio project file is provided for the sample source code.

To build the sample plug-in:

1. Using Microsoft Visual C++ 4.2 or later, open the included project file, SampleVisualPlugin.dsp.

2. Build the SampleVisualPlugin.rpv file.

   	Note
   	The SampleVisualPlugin.rpv file is copied to the C:\Program Files\Common Files\Real\Visualizations folder. The SampleVisualPlugin.rpv file must reside in this folder.

3. If RealJukebox is running, right-click on the visualization pane. Sample Visual Plugin should be listed in the visualization list.

4. Play some music and select Sample Visual Plugin from the visualization list.

Congratulations! You have successfully built and installed a visualization plug-in.

Debugging a Plug-In

You should be able to use your standard debugger to debug visualization plug-ins. In Visual C++, you can set the debugging settings in your DLL's project to use realjukebox.exe as the application for debugging.

Testing a Plug-In

Perform as much real-world testing of your plug-ins as possible. Be sure to test under conditions that are less than ideal. For example, try running your visualization while ripping a CD.

Copyright © 2000 RealNetworks
For information on RealNetworks' technical support, click here.
This file last updated on 09/14/00 at 17:21:33.