Product Support

1201 - Graphics Rendering and Troubleshooting Guide

Section 1: What Rendering Options Are Available?

MATLAB supports three graphics Renderers: Painters, ZBuffer, and OpenGL:

Painters:	Original rendering method of MATLAB. This is faster when the figure contains only simple or small graphics objects. Painters does not support lighting or transparency.
ZBuffer:	MATLAB draws 3-D graphics objects faster and more accurately. This is because objects are colored on a per pixel basis and MATLAB renders only those pixels that are visible in the scene (thus eliminating front-to-back sorting errors). This Renderer allows for lighting objects. This method can consume a lot of system memory if MATLAB is displaying a complex scene.
OpenGL:	OpenGL became available as an additional rendering method to complement ZBuffer and painters. This Renderer is generally faster than Painters or ZBuffer, and in some cases enables MATLAB to access graphics hardware if it is available on your machine. It provides object transparency, lighting, and accelerated performance.

OpenGL is an application program interface (API) that has become the computer industry standard for complex computer graphics such as 3-D images and animations. The OpenGL interface provides functions that an application uses to draw. These functions can be implemented either in software or in hardware, when available. Hardware implementation is generally faster.

Section 2: How Does MATLAB Choose a Renderer?

In MATLAB 6.0 (R12), a few features were added to enhance the graphics. The two primary enhancements were the addition of the OpenGL graphics rendering method and the rendering auto-selector. These correspond to the figure properties Renderer and RendererMode. The figure's Renderer property can take one of the following values, which are described in the previous section:

Painters
Zbuffer
OpenGL

The figure's RendererMode property can take one of the following values:

auto
manual

When set to auto , MATLAB will decide which Renderer property is most appropriate for the given figure. When set to manual, the Renderer property can only be changed manually.

To learn more, refer to the online documentation for the following figure properties in MATLAB 6.5 (R13):

OpenGL is available on all platforms that run MATLAB. MATLAB automatically finds hardware versions of OpenGL if they are available. If the hardware version is not available, then MATLAB uses the software version.

Section 3: How Can I Control Which Renderer Is Being Used?

As described earlier, if the figure's RendererMode property is set to manual, you can manually set the Renderer property to any of the three rendering modes. Additionally, by setting the Renderer property, the RendererMode is automatically set to manual. For example, the following line of code will set the current figure's Renderer to painters, regardless of subsequent changes to the figure contents.

set(gcf, 'Renderer', 'painters')

You can also specify that OpenGL is never selected when MATLAB automatically selects the most appropriate Renderer. To do this, you need to familiarize yourself with the OPENGL command by typing the following at the MATLAB command prompt:

help opengl

Pay particular attention to the OPENGL command arguments NEVERSELECT and AUTOSELECT. The NEVERSELECT argument will cause MATLAB to never select OpenGL as the figure's Renderer. This option can be useful when troubleshooting possible conflicts with OpenGL. The AUTOSELECT argument enables MATLAB to automatically choose OpenGL if it is available and if it is appropriate. This is the default setting. The criteria for auto selection appropriateness are outlined in the online documentation for MATLAB 6.5 (R13) under the RendererMode figure property.

If you would like all of the figures in your MATLAB session to use a specific rendering method, you can set the default figure Renderer. For example, if you would like all of your figures to use OpenGL, then use the following syntax:

set(0,'DefaultFigureRenderer','opengl')

For more information on this syntax, consult Technical Note 1205. By placing the above line of code in a startup.m file on the MATLAB search path, it will set the default figure Renderer to OpenGL for all subsequent MATLAB sessions.

How do I choose which Renderer to use for my application?

More information regarding the pros and cons of each Renderer can be found in the Using MATLAB Graphics documentation in the section titled Selecting a Renderer.

Section 4: How Can I Tell if OpenGL Is the Source of Problems While Running MATLAB with Graphics?

This section can help you to diagnose an OpenGL-related problem. If you determine that OpenGL is the source of a problem, follow the steps outlined in Section 8: Will Changing My Graphics Adapter's Driver Help Resolve My Problem?

OpenGL problems are usually caused by incompatible hardware, bugs in the hardware driver, or incorrect system configuration. Problems related to OpenGL can cause the following types of unexpected behavior:

Graphics render poorly or not at all
Erratic display of a graphics figure or GUI window
MATLAB Segmentation Violation when using graphics, including when executing:
```
opengl info
```
or
```
bench
```

To diagnose whether OpenGL may be the source of a problem, you will first need to determine where MATLAB is getting its OpenGL instructions, from hardware or software.

Is MATLAB using hardware or software OpenGL?

To determining this, type the following at the MATLAB command prompt:

opengl info

You will receive output in the following format:

Version = 1.1.3 Dec 20 2000

Vendor = Matrox Graphics Inc.

Renderer = Matrox G400

MaxTextureSize = 2048

Extensions = GL_ARB_multitexture GL_ARB_texture_env_add _

On a PC, you may notice that your vendor is Microsoft. If this is the case, then you are most likely using the Microsoft software driver. In general, software OpenGL conflicts are rare.

If hardware is being used, you will get information regarding your driver. You can test to see if MATLAB 5.3 (R11) or later is using OpenGL correctly by executing the following sample commands:

x=[0 0 1]; y=[1 2 2]; z=[1 1 1]; 
hp = patch(x,y,z); 
colormap(autumn(3)) 
set(hp,'FaceVertexCData',[1;2;3]) 
set(hp,'FaceColor','interp','EdgeColor','interp') 
title('Smooth interpolation using OpenGL') 
set(gcf,'Renderer','OpenGL')

You should not receive any warnings or errors, and the figure should look similar to the following:

Is the OpenGL driver working correctly?

To check if the OpenGL driver is working correctly on Windows, try to run an OpenGL screen saver in the following manner. Right-click on the Windows desktop and select Properties. In the ensuing dialog box, select the Screen Saver tab and run an OpenGL screen saver, such as 3-D pipes.

If this screen saver does not work correctly, then you most likely do not have the graphics adapter's driver installed properly. On some machines, you can completely disable the hardware acceleration to see if avoiding hardware alleviates the problem. Right-click on the Windows desktop and select Properties. In the ensuing dialog box, select the Settings tab and click Advanced. On this page, select the Troubleshooting or Performance tab, and slide the Hardware acceleration slider all the way to the left. Now click OK on each of the dialog boxes.

Another source of problems is that some drivers do not work well at certain color depths. The Settings tab has a pop-up menu labeled Colors that allows choices such as 256 colors, 16-bit, 24-bit, and 32-bit. Try different selections. Some cards only work well at 16-bit or 32-bit.

Consult your system and hardware graphics documentation for proper configuration procedures before continuing to troubleshoot a possible conflict with MATLAB.

For information regarding the setup of OpenGL on UNIX, see Solution 1-17YM3.

Section 5: How Can I Determine If OpenGL Is Causing Specific Erratic Behavior in My Figure?

If a figure is not displaying as expected, first find out what Renderer is being used by executing the following command at the MATLAB prompt:

get(gcf,'Renderer')

If you desire OpenGL and it is not being selected, it is possible that MATLAB is set up to ignore OpenGL. See Section 3: How Can I Control Which Renderer Is Being Used?

If OpenGL is being selected and you do not require transparency, you can change the figure's Renderer to Zbuffer to see if this fixes the problem.

set(gcf,'Renderer','Zbuffer')

Also, you will be able to narrow the problem down to OpenGL if executing the following line of code prohibits you from reproducing the problem:

opengl neverselect

Section 6: Are There Any Hardware or Software Incompatibilities?

A comprehensive list of incompatible graphics adapters and drivers would not be feasible. The conflicts can depend on a combination of the operating system, the adapter's chipset, and the driver version. Since new driver releases commonly occur more often than new MATLAB releases, it would be impossible to fully test each combination.

However, the following is a list of commonly found problems that have been encountered. If you think you may have a conflict, read Section 4: How Can I Tell if OpenGL Is the Source of Problems While Running MATLAB with Graphics?

Hardware: ATI RAGE MOBILITY chipset
Hardware: S3 chipset

We have seen some problems with the ATI Rage Mobility and S3 chipsets in MATLAB 6.1 (R12.1) and earlier. You can generally obtain the chipset by locating the vendor information in the output of the following MATLAB command:

opengl info

As a possible workaround, see Section 8: Will Changing My Graphics Adapter's Driver Help Resolve My Problem?

Hardware: NVIDIA TNT2 graphics adapter

NVIDIA TNT2 cards are currently not supported with Windows 2000. Detailed information can be found in Solution 1-18DUA2.

Hardware/Software: Windows 2000 and Matrox video cards

If you are using Windows 2000 in conjunction with one of several Matrox video cards (the G450 and G550 are known to be problematic), it is possible that certain MATLAB operations can cause Windows to crash. This issue is specific to MATLAB 7.0 (R14), and is detailed in Solution 1-O3B5D.

Section 7: What Unexpected Behavior Might I Encounter When Using OpenGL?

OpenGL restrictions and limitations

The restrictions and limitations when using OpenGL can be found in the documentation for the figure property Renderer. In particular, pay attention to the sections titled "OpenGL vs. Other MATLAB Renderers" and "Criteria for Autoselection of OpenGL Renderer."

Erase Modes

Figure property values for the EraseMode property other than normal are not supported by the OpenGL Renderer. Therefore, it is not possible to have transparency and an EraseMode of none at the same time.

Perceived slower figure creation in MATLAB 6.1 (R12.1) and higher

The first time a MATLAB figure window is created, the OpenGL drivers are loaded. This can add a few seconds to the load time of the first figure. Subsequent figures open faster than they did in previous versions of MATLAB.

Section 8: Will Changing My Graphics Adapter's Driver Help Resolve My Problem?

Getting the correct drivers is the most important factor in getting OpenGL to work well. It is very common for a vendor to ship graphics adapters before the software is fully tested. As a result, the drivers can have many bugs in them. You should visit your vendor's technical support Web site on a regular basis to see if there are updated drivers. In general, you will want to find the latest driver version that is Windows Hardware Quality Lab (WHQL) certified.

New drivers are frequently released with fixes and enhancements. Sometimes these new driver features will resolve conflicts with MATLAB, and sometimes they will create conflicts. Therefore, we recommend that you try replacing your current driver with a newer or older version to see if this helps resolve the problem. Replacing the driver can resolve many problems ranging from system crashes to MATLAB crashes to erratic graphics rendering.

If you are running Windows 95, 98, or ME, you could try using GLSetup (www.glsetup.com). This is a utility that automatically selects the best drivers for your card. It is not yet available for UNIX, Windows NT, Windows 2000, or Windows XP. The Web page has helpful information about different types of graphics cards.

If you are interested in more technical details, visit the following OpenGL Web site:

http://www.opengl.org/documentation/index.html

If changing the driver does not help, as a last resort, try using software OpenGL as described in section 9.

Section 9: How Can I Point My Computer to the Desired Software or Hardware OpenGL?

Windows

As of MATLAB 6.1 (R12.1), you can select the generic software OpenGL Renderer for Windows by using the following command:

feature('UseGenericOpenGL',1)

By placing the above line of code in a startup.m file on the MATLAB search path, software OpenGL will be used for all subsequent MATLAB sessions.

Additional information can be found in the MATLAB 6.5 (R13) online documentation.

As mentioned previously, software OpenGL rarely exhibits conflicts. Therefore, this is a great alternative to hardware OpenGL if you are running MATLAB 6.1 (R12.1) or later.

UNIX

How do I direct MATLAB to use the Mesa OpenGL Libraries or the System OpenGL Libraries on a UNIX machine?

Specific Linux hardware problem

Relevant information on setting up the OpenGL libraries for LINUX systems can be found at the online resolution Why does my Linux hardware OpenGL not work?

Section 10: What Should I Do If None of the Troubleshooting Suggestions Resolves My Problem?

This Technical Note is intended to capture the most common problems related to OpenGL. If you are experiencing specific erratic behavior in MATLAB graphics and this document does not resolve the issue, it is possible that it is a bug in MATLAB. In this case, you can search for a resolution in our Knowledge Base.

If you have diagnosed the problem as being an OpenGL conflict with MATLAB and you are unable to resolve the problem as discussed in this document, we recommend that you disable OpenGL as a rendering option in MATLAB. To do this, create or edit a startup.m file and place the following command in it:

opengl neverselect

Make sure that the file is saved on the MATLAB search path. This will prevent MATLAB from using OpenGL as the default renderer.

Alternatively, you could try using a program called GLDirect, which uses Direct3-D to emulate OpenGL. Information can be found at:

http://www.scitechsoft.com/products/ent/gld_home.php

If you continue to experience problems with OpenGL, log a Web Support Request. Be sure to include:

The output of ver typed at the MATLAB command prompt
The output of opengl info typed at the MATLAB command prompt
Your graphics adapter information
Your driver information
A detailed description of the problem you are encountering

Products & Services	Industries	Academia	Support	User Community	Company