Hardware Acceleration

Mac OS X allows you to take advantage of hardware graphics acceleration for your Java Swing graphics. If enabled, this technology passes swing graphics calls directly to the video card. This can result in significant speed increases for your graphics intensive Java applications. Java 1.3.1 Update 1 includes an implementation of hardware graphics acceleration that is much improved from previous releases of this technology. Along with increased robustness and effectiveness of the Java graphics hardware acceleration in this release, the procedure for turning it on has changed.

Previous releases of Java on Mac OS X used the com.apple.hwaccel flag to turn hardware acceleration on. In this release though, you use the com.apple.hwaccellist flag followed by a list of video cards that you want hardware acceleration turned on for. This gives you more flexibility in providing the best end user experience for your application. If your application does not need hardware video acceleration, do not supply the com.apple.hwaccellist flag. If hardware acceleration only shows marked improvement on systems with higher end video cards, only turn it on for those systems.

“Supported Graphics Cards” gives more information on determining the video card names to use in the list. “Enabling Hardware Acceleration From the Command Line” and “Enabling Hardware Acceleration In Mac OS X Application Bundles” give examples of how to turn it on in your application.

When considering turning on hardware acceleration, it is important to note that its effectiveness is closely tied to the of video memory available. The more video memory available, the greater benefits you should see from turning on hardware acceleration. Though you can turn on hardware acceleration for video cards with less than 16 MB of video memory, they are generally not supported simply because the cards do not have enough memory to show an increase in performance. They may even show a decease as the hardware acceleration implementation tries to balance the graphics display between the minimum resources of the video card and the more extensive resources of the operating system.

Mac OS X’s implementation of hardware acceleration attempts to protect you from the details of how it works by incorporating an intelligent heuristic algorithm to regulate the usage of the video card. Even if you have turned hardware acceleration on for certain video cards, Mac OS X’s will try to only use it where it brings benefits. This is not an exact science though since impending actions are unpredictable. This means that while turning on hardware acceleration usually gives you tremendous benefits, forcing it on for systems with lower amounts of video memory may cause a decrease in performance. Although the heuristic attempts to make good decisions, it must work under the premise that you want hardware acceleration turned on for that particular card. It is now biased toward running the graphics display directly from the video. On systems with enough video memory this produces the desired effect of increased performance. On systems with lower amounts of video memory, less than 16MB at least, the benefits to be seen in hardware acceleration will by overshadowed by the resources required to compensate for the small amount of video memory available.

Supported Graphics Cards

Java hardware graphics acceleration is supported on most of the video cards provided by default in Apple’s computers. For the purpose of Java graphics hardware acceleration, each of these cards has been designated a distinct identifying string. When invoking hardware acceleration, you specify which graphics card’s hardware acceleration should be turned on for by setting the com.apple.hwaccellist system property to the appropriate string or list of comma separated strings. Examples follow in “Enabling Hardware Acceleration From the Command Line” and “Enabling Hardware Acceleration In Mac OS X Application Bundles”.

You can determine a specific system’s designation by running the hwaccel_tool, viewing the list in /Library/Java/Home/lib/glconfigurations.properties or seeing what is specified inTable 2-1.

Table 2-1 Java Hardware Graphics Acceleration Video Card Designation Strings

Enabling Hardware Acceleration From the Command Line

To run your application from the command line with hardware acceleration turned on, you simply pass in the com.apple.hwaccellist flag followed by a list of video card designation strings. An example of turning on hardware acceleration for a single video card follows:

java -Dcom.apple.hwaccellist=NVidia20_67108864 -jar App.jar

For multiple cards:

java -Dcom.apple.hwaccellist=ATIRage128_16777216,ATIRage128_33554432 -jar App.jar

Enabling Hardware Acceleration In Mac OS X Application Bundles

If you distribute your Java application within a Mac OS X application bundle you need to modify the application properties to include the hardware acceleration flags. If you are modifying a previously built application:

1. Navigate to the appropriate property file in your applications bundle. For an application built with MRJAppBuilder this file is in YourApplicationBundle.app/Contents/Info.plist. For an application built in Project Builder it is inYourApplicationBundle.app/Contents/Info.plist.

   Note: The Finder hides the contents of an application bundle, as well as the .app extension. To show an application bundle’s contents in the Finder, you can control click on the application icon and choose Show Package Contents.



2. Add a com.apple.hwaccellist key with a comma separated list of values from Table 2-1. Both of these keys are set under the Java dictionary in the Application dictionary hierarchy. You may use any text editor or /Developer/Applications/Property List Editor. A simple example of a modified property list follows:

<dict>
    <string>????</string>
    <key>CFBundleVersion</key>
    <string>0.1</string>
    <key>Java</key>
    <dict>
        <key>ClassPath</key>
        <string>$JAVAROOT/SwingTest.jar</string>
        <key>MainClass</key>
        <string>SwingTest</string>
        <key>Properties</key>
        <dict>
            <key>com.apple.macos.useScreenMenuBar</key>
            <string>true</string>
            <key>com.apple.mrj.application.apple.menu.about.name</key>
            <string>SwingTest</string>
            <key>com.hwaccellist</key>
            <string>ATIRage128_16777216,ATIRage128_33554432</string>
        </dict>
    </dict>
</dict>
</plist>

If you are building a new application in Project Builder you can set these values in the Applications Settings tab.

1. With your project open in Project Builder click the Targets tab.


2. Select Edit Active Target from the Project menu.


3. Click the Application Settings tab.


4. In the top right corner of the Application Settings pane is the option to edit in Simple or Expert mode. Click Expert.


5. Near the bottom of the list should be a Java disclosure triangle. Click it.


6. This will reveal a Properties disclosure triangle. Click it.


7. Select one of the items already there and click New Sibling.


8. In the Property List column, enter hwaccelllist. In the Value column append the appropriate strings from Table 2-1.

If you are using MRJAppBuilder to wrap an existing Java application as a Mac OS X executable bundle:

1. Click on the Java Properties tab.


2. Click Add.


3. In the property field of your new property add com.apple.hwaccellist.


4. Set the value field set to a string or a comma separated list of strings from Table 2-1.

Enabling Hardware Acceleration Using Keyboard Commands

While testing your Java applications you may want to see what effect Mac OS X’s Java hardware graphics acceleration has on your code without explicitly modifying your application’s runtime environment. There are two sets of key combinations to do this:

• Command-F7 attempts to turn on hardware acceleration. This is roughly equivalent to including a listing for your video card in the hwaccellist property. It incorporates the algorithm to check to see if hardware acceleration can provide perceived benefit before turning it on. Option-F7 turns it off.


• Command-F8 forces hardware acceleration on. This is not as kind as the above method. It completely bypasses the normal heuristic to determine if it should be on and just turns it on. This is for testing only, and you may see unpredictable results. Option-F8 turns it off.

Note: You may see graphical garbage on the screen if you force hardware acceleration on with Command-F8. This is a known issue.

Note: Once you have forced hardware acceleration on with Command-F8, you can no longer use Command-F7 to turn it on without running you application again.