sgl_lib

8/8/2019 sgl_lib

1/57

MATLAB C/C++

The Language of Technical Computing

Computation

Visualization

Programming

User s Guide

Version 1

Graphics Libra ry

8/8/2019 sgl_lib

2/57

How to Contact The MathWorks:

508-647-7000 Phone

508-647-7001 Fa x

The MathWor ks, Inc. Ma il

3 Apple Hill Drive

Na tick, MA 01760-2098

h t t p : / / www. ma t h wo r k s . c o m Web

f t p . ma t h wo r k s . c o m Anonymous FTP server

c o mp . s o f t - s y s . ma t l a b Newsgroup

s u p p o r t @ma t h wo r k s . c o m Technical support

s u g g e s t @ma t h wo r k s . c o m Product enhancement suggestions

b u g s @ma t h wo r k s . c o m Bug report s

d o c @ma t h wo r k s . c o m Docum enta tion error report ss u b s c r i b e @ma t h wo r k s . c o m Subscribing user registra tion

s e r v i c e @ma t h wo r k s . c o m Order s ta tu s, license r enewals, passcodes

i n f o @ma t h wo r k s . c o m Sales, pricing, and general information

MAT LA B C/ C++ Graph ics Library Users Guid e

The softwar e described in this documen t is fur nished un der a license agreem ent. The softwar e may be usedor copied only under t he ter ms of the license agreem ent. No part of th is manu al may be photocopied or repro-duced in any form with out prior writt en consent from The MathWorks, Inc .

FEDE RAL ACQUISITION: This provision applies to all acquisitions of th e Program an d Docum enta tion byor for the federal governm ent of the United Sta tes. By accepting delivery of the Program , the governm enthereby agr ees tha t th is software qua lifies as "commer cial" compu ter software with in th e mean ing of FARPar t 12.212, DFARS Pa rt 227.7202-1, DFARS Part 227.7202-3, DFARS Part 252.227-7013, and DFARS Par t252.227-7014. The term s and conditions of The Mat hWorks, Inc. Software License Agreemen t sha ll pertainto the governm ents use and disclosur e of the Program a nd Documen tat ion, an d shall supersede an yconflicting contra ctual ter ms or conditions. If this license fails to meet th e governm ents minimu m n eeds oris inconsistent in any r espect with federal procurement law, the government agrees to return the P rogramand Document ation, unused, to Math Works.

MATLAB, Simulink, Sta teflow, Handle Grap hics, an d Real-Time Workshop are registered t rad emar ks, andTarget Language Compiler is a tradema rk of The MathWorks, Inc.

Other product or brand n ames ar e tra demarks or registered tradema rks of their respective holders.

Pr in t ing History: June 1999 New for Ver sion 1 .0 , Release 11 (Online on ly)

Ja nua ry 2000 Revised for Version 1.0.2, Release 11 (Online only)

8/8/2019 sgl_lib

3/57

i

Contents

1

Introduction

The MATLAB C/C++ Graph ics Library . . . . . . . . . . . . . . . . . . 1-2

Component s of th e MATLAB C/C++ Gra ph ics Libra ry . . . . . . . 1-2

Rest r ictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Sour ces of Addit iona l In form at ion . . . . . . . . . . . . . . . . . . . . . . . 1-6

Inst allin g th e MATLAB C/C++ Graph ics Libra ry . . . . . . . . . 1-7Before You In st a ll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Syst em Requ irem ent s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Download ing a nd In st allin g on PCs . . . . . . . . . . . . . . . . . . . . . . 1-8

Downloadin g and Ins ta lling on U NIX System s . . . . . . . . . . . . 1-10

Configuring the MATLAB C/C++ Graphics Library . . . . . . 1-14

Configurin g th e Gra ph ics Libra ry on P Cs . . . . . . . . . . . . . . . . 1-14

Configurin g the Gra ph ics Librar y on UN IX System s . . . . . . . 1-16

2

Creatin g Stan d-Alone Graphic s Applications

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3

Building a S tand-Alone Graphics Application . . . . . . . . . . . 2-5

Build ing Gr ap hics Applicat ions on a P C . . . . . . . . . . . . . . . . . . 2-5

Building Gra phics Applicat ions on a U NIX System . . . . . . . . . 2-7

Run nin g th e MATLAB Compiler Out side MATLAB . . . . . . . . . 2-9

Cha nges in Ru n-tim e Beha vior a nd Appea ra nce . . . . . . . . . . . 2-10

Pack aging a Graphics Application for Redistribution . . . 2-13

Pa ckaging Gra phics Applications on a PC . . . . . . . . . . . . . . . . 2-13

Pa ckaging Gra ph ics Applicat ions on a UNI X System . . . . . . . 2-14

8/8/2019 sgl_lib

4/57

i i Contents

Compiling and Linking Translated M-Files . . . . . . . . . . . . . 2-15

Compiling Tra ns lat ed M-Files . . . . . . . . . . . . . . . . . . . . . . . . . 2-15

Link ing wit h MATLAB Libra ries . . . . . . . . . . . . . . . . . . . . . . . 2-15

3

Troubleshooting

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Usin g Uns upp orted MATLAB 5.3 Feat ur es . . . . . . . . . . . . . . . . 3-2Compiling Applicat ion Wr itt en a s Script s . . . . . . . . . . . . . . . . . 3-3

Fixin g Callba ck Pr oblems: Illegal Syn ta x . . . . . . . . . . . . . . . . . 3-4

Fixing Callba ck P roblems: Missing Fu nctions . . . . . . . . . . . . . . 3-7

Dependin g on Gra phics Sett ings in Sta rt -Up Files . . . . . . . . . . 3-9

Pr int Option Does Not Appear on File Menu . . . . . . . . . . . . . . . 3-9

4

Reference

MATLAB C/C++ Graphics Library . . . . . . . . . . . . . . . . . . . . . . 4-2

MATLAB 5.3 Built -In Gr ap hics F unct ions . . . . . . . . . . . . . . . . . 4-2

MATLAB 5.3 M-File Gra ph ics Fu nct ions . . . . . . . . . . . . . . . . . . 4-3

8/8/2019 sgl_lib

5/57

1

Introduction

The MATLAB C/C++ Graphic s Libra ry . . . . . . . . 1-2

Component s of th e MATLAB C/C++ Graph ics Library . . . 1-2Rest riction s . . . . . . . . . . . . . . . . . . . . . 1-3

Sources of Additiona l Informa tion . . . . . . . . . . . . 1-6

Inst allin g th e MATLAB C/C++ Graph ics Libra ry . . . . 1-7

Before You Ins t all . . . . . . . . . . . . . . . . . . 1-7

Syst em Requirem ent s . . . . . . . . . . . . . . . . . 1-7

Downloadin g an d Ins ta lling on PCs . . . . . . . . . . . 1-8

Downloading an d Inst alling on UNIX Systems . . . . . . 1-10

Configuring the MATLAB C/C++ Graphics Library . . 1-13

Configuring th e Graph ics Library on PCs . . . . . . . . . 1-13

Configuring th e Graph ics Library on UNIX Systems . . . . 1-15

8/8/2019 sgl_lib

6/57

1 Introduction

1-2

The M ATLAB C/ C++ Graphics LibraryThe MATLAB C/C++ Gra ph ics Libr ar y is a collection of MATLAB gra phics

routines distr ibuted as a single library. The gra phics libra ry mak es the

visualization and GUI-building routines of MATLAB available to stand-alone

C an d C++ applicat ions . A st an d-alone C or C++ app licat ion is a n executa ble

program th at can r un independent ly of th e MATLAB int erpret ed environment .

Sta nd-alone ap plicat ions a re a convenient wa y to package an d distr ibute a

customized MATLAB a pplication.Using th is librar y, in conjun ction with t he MATLAB Compiler a nd t he

MATLAB C/C++ Math Libra ry, you can crea te st an d-alone a pplicat ions from

M-files t ha t use lines, text, meshes, a nd polygons as well as intera ctive

graph ical user int erface component s such as m enus, pu sh but tons, and dialog

boxes.

Note You mu st u se th e MATLAB Compiler t o creat e C or C++ st an d-alonegra phics applications. Calling MATLAB C/C++ Graph ics Libra ry rout ines

directly from a C or C++ source module is not su pport ed.

The following sections pr ovide inform at ion a bout:

Component s of th e MATLAB C/C++ Graph ics Libr ar y on pa ge 1-2

Restrictions on page 1-3 Sources of Additional Information on page 1-6

After readin g th ese sections, continue with Ins ta lling th e MATLAB C/C++

Gra phics Librar y on page 1-7 and then read Configur ing t he MATLAB C/C++

Gra phics Librar y on page 1-14.

Components of the M ATLAB C/ C++ Gra phics Libra ryThe MATLAB C/C++ Graph ics Library cont ains more th an 100 routines,

including:

MATLAB 5.3 built-in gr aph ics functions, su ch a s s u r f , p l o t , g e t , and s e t

Some comm only used MATLAB 5.3 M-file gra ph ics fun ctions , such as

n e wp l o t , g c f , g c a , g c o , and g c b f

8/8/2019 sgl_lib

7/57

The M ATLAB C/ C+ + G raphics Library

1-3

For a complete list of th e routines included in t he gra phics library, see Chapter4, Referen ce.

Note While only a s ubset of MATLAB M-file grap hics functions a re in cludedin t he MATLAB C/C++ Gra phics Libra ry, th e MATLAB Compiler can compile

man y others graph ics M-files, if th ey are included in a graph ics a pplicat ion.

RestrictionsThe MATLAB C/C++ Graph ics Libra ry su pport s most MATLAB 5.3 feat ur es,

including mu ltidimensiona l arr ays, cell ar ra ys, an d stru ctu res. However, th ere

ar e some MATLAB feat ur es th e graph ics librar y does not s upport, including:

MATLAB int eger types (i n t 8 , i n t 1 6 , i n t 3 2 , u i n t 8 , u i n t 1 6 , and u i n t 3 2 )

MATLAB objects

OpenGL

p l o t e d i t command

In a ddition t o th ese restrictions,th e graph ics library pr ovides limited supp ortfor printing and certain callback coding pra ctices.

Note The gra phics library is su bject to the s ame limita tions as t he MATLABCompiler an d t he MATLAB C/C++ Mat h Librar y. For exa mple, MATLAB

fun ctions th at require t he MATLAB interpr eter, most nota bly e v a l ( ) and

i n p u t ( ) , are n ot su pport ed. See the MATLAB Comp iler an d MATLAB C/C++

Math Library docum ent at ion for inform at ion a bout th eir restr ictions.

Graphics Library Printing Support

The graph ics library supports pr inting in sta nd-alone graph ics applicat ions,with some r estrictions.

Default Printing. If your application uses default p r i n t comma nd set tings, it

should r equire n o modificat ion. When a user of your sta nd-alone graph ics

applicat ion selects th e Prin t option on t he figur e window File menu, the p r i n t

comman d execut ed by defau lt sends t he cur rent figure to whatever prin ter t he

8/8/2019 sgl_lib

8/57

1 Introduction

1-4

user ha s set up a s the default printer on th eir system. In addition, the graph icslibra ry honors a ny figure or a xes properties your applicat ion s ets t o cust omize

the printed out put.

Custom Printing. If your ap plicat ion u ses p r i n t comm an d switches t o specify

device drivers a nd other options, be aware t ha t t he graph ics librar y supports

only a su bset of th ese switches. For example, the gra phics library su pport s

most of the MATLAB built-in drivers, such a s t he P ostScript d rivers. However,

th e graphics librar y does not supp ort an y of th e Ghostscript dr ivers.

Table 1-1 lists th e device drivers sup ported by th e graph ics library. For more

inform at ion a bout s pecifying device drivers , see Pr int ing MATLAB Gra ph ics

in Using MATL AB Graphics.

Tab le 1-1 : Device Drivers Supported by the Gra phics Libra ry

Device Description

d b i t ma p Windows Bitma p (BMP) forma t (Windows only)

d e p s Level 1 black and wh ite En capsu lated PostScript (EPS)

d e p s c Level 1 color Encapsulated PostScript (EPS)

d e p s 2 Level 2 black and wh ite En capsu lated PostScript (EPS)

d e p s c 2 Level 2 color Encapsulated PostScript (EPS)

d h p g l HP GL compatible with H P 7475A plott er

d i l l Adobe Illustrator 88 compatible illustration file

d p s Level 1 black an d wh ite PostScript

d p s c Level 1 color PostScript

d p s 2 Level 2 black an d wh ite PostScript

d p s c 2 Level 2 color PostScript

d wi n Windows black a nd wh ite pr int ing ser vices. (Windows only)

d wi n c Windows color pr int ing services. (Windows only)

8/8/2019 sgl_lib

9/57

The M ATLAB C/ C+ + G raphics Library

1-5

In a ddit ion t o device drivers, t he MATLAB p r i n t comman d supports severa lcomman d-line options th at cont rol var ious aspects of th e prin t job, such as th e

ren derer used. The graphics librar y supports th e subset of th ese options tha t

ar e listed in Table 1-2. For a complet e list of prin t comm an d options, see

Pr int ing MATLAB Gr aph ics in Using MAT LAB Graphics.

Unsupported Application Coding Practices

Certain coding practices, used mainly in callback strings in graphics M-files,

tha t are supported in th e MATLAB interpreted environment are n ot su pported

in st an d-alone gra ph ics app licat ions . For example, MATLAB allows you tospecify ma th expressions in a callback pr operty strin g. This is not supported in

sta nd-alone gra phics applicat ions. See Chapter 3, Troubleshooting for more

inform at ion a bout un supported coding practices and how to work a round t hem.

Tab le 1 -2: print Command Line Options Supported by the Graphics Libra ry

Option Description

a d o b e c s e t Use PostScript defau lt chara cter set encoding

a p p e n d Append to existing PostScript file without overwriting

c my k Use CMYK colors in Post Script in st ead of RGB

n o u i Suppr ess print ing of user int erface cont rols

r n u mb e r Specify resolut ion in dots per inch

p a i n t e r s Render using Pa int ers algorith m

z b u f f e r Render usin g Z-buffer

8/8/2019 sgl_lib

10/57

1 Introduction

1-6

Sources of Additional Inform a tionThis ma nu al describes th e MATLAB C/C++ Graph ics Librar y but it does not

describe how t o use MATLAB graph ics or s pecific MATLAB gra ph ics fun ctions .

This t able lists sources of additiona l inform ation about th ese topics a nd oth er

topics rela ted t o us ing th e MATLAB C/C++ Graph ics Libra ry. The online

reference docum enta tion is available th rough t he MATLAB Help Desk.

Topic Document

Usin g MATLAB graph ics

functions

Using MATL AB Graphics

Building gra phical user

interfaces

Building GUIs with M ATLA B

Ind ividual MATLAB

graphical functions

Online MATLAB Function Reference

Usin g th e MATLAB

Compiler

MAT LA B Com piler Users Guid e

Usin g th e MATLAB

C/C++ Mat h Librar y

MAT LAB C Math Library Users Guide

MAT LA B C++ Math Library U sers Guid e

Ind ividual MATLAB C and

C++ math fun ctions

Online MAT LAB C Math L ibrary Function

Reference

Online MA TL AB C++ Math Library

Function Reference

8/8/2019 sgl_lib

11/57

Installing the M ATLAB C/ C + + G raphics Library

1-7

Insta lling the M ATLAB C/ C++ Graphics Libra ryThe MATLAB C/C++ Graph ics Libra ry is ava ilable as a d ownloada ble product

from th e Mat hWork s Web site. This section describes:

Installation prerequisites in Before You In st all on pa ge 1-7

System Requirem ent s on page 1-7

Downloadin g an d In st alling on PCs on pa ge 1-8

Downloadin g an d Ins ta lling on U NIX System s on page 1-10

After reading th is section, cont inue with Configuring the MATLAB C/C++

Gra ph ics Libra ry on page 1-14.

Before You Insta llBefore you can insta ll and use t he MATLAB C/C++ Graph ics Librar y, you mu st

ha ve a valid license for t his pr oduct. When you pur chase a MATLAB produ ct,

The Mat hWorks sends you your license in an e-ma il message. If you ha ve not

received your license, contact The MathWorks immediately via:

The Web at www. ma t h wo r k s . c o m/ ml a . Log in t o MATLAB Access u sing your

last na me a nd Access nu mber . MATLAB Access m embers hip is free of char ge

an d available to all cust omers. The prima ry cont act on each license is

au toma tically enrolled in MATLAB Access and receives an Access n um ber

via e-ma il from Th e Mat hWorks.

E-mail at s e r v i c e @ma t h wo r k s . c o m

Telephone a t 508-647-7000, ask for Cu st omer Ser vice

Fa x at 508-647-7001

System Requirem ents

Software. To use t he MATLAB C/C++ Graph ics Libra ry to crea te a st an d-alone

C or C++ application requires several other MATLAB products:

MATLAB Vers ion 5.3.1

MATLAB Compiler Version 2.0.1

MATLAB C/C++ Mat h Libra ry Version 2.0.1

You mu st also have inst alled on your system a n ANSI C or C++ compiler.

8/8/2019 sgl_lib

12/57

1 Introduction

1-8

Hardware. The MATLAB C/C++ Graph ics Libra ry is availa ble for PCs ru nn ing

Microsoft Windows or Linux an d for Sun , HP, SGI, and Alpha UN IX plat form s.

The MATLAB C/C++ Grap hics Librar y is not su pport ed on IBM RS/6000

systems.

For th e most up -to-dat e inform at ion a bout th e systems su pported by MATLAB,

Release 11, see the System Requirement s page in th e Products ar ea at t he

Math Work s Web site, www. ma t h wo r k s . c o m.

Dow nloading a nd Installing on PCsTo download an d inst all th e graph ics library on a PC, follow th ese instr uctions.

1 Go to The Math Works Web site, www. ma t h wo r k s . c o m, an d click on t he

Downloads selection listed u nder Quick Link s.

2 If you h ave your Per sonal Licens e Pa ssword, click on th e Download

Products link. If you do not ha ve your PLP, follow th e appr opriate link to

obta in it.

3 En ter your na me a nd MATLAB Access nu mber.

4 Select t he t ype of system on wh ich you wan t to ru n t he gra phics library from

th e list of supported system s, and t hen click th e Continue but ton. You can

select mu ltiple systems.

5Select t he MATLAB C/C++ Gra phics Libra ry from t he list of produ cts youar e licensed to insta ll, an d th en click t he Continue button.

6 Download t he r equired product ar chives, and a ny optiona l product a rchives,

by right-clicking on th eir links a nd selecting t he sa veoption pr ovided by

your browser. You can specify th e folder int o which you wa nt to download

th e product ar chive and th e nam e you wan t assigned to the archive.

7 When t he download is comp lete, view the conten ts of your download folder

an d double-click on t he gra phics librar y archive. This st ar ts th e MATLABinsta llation program. F ollow th e inst ru ctions included in each dialog box

displayed by the installation program. You will need your license

informa tion to complete t he inst allation.

8/8/2019 sgl_lib

13/57


1-9

Note Make su re t here is spa ce available in your system s tem pora rydirectory before sta rt ing the inst allation program. The nam e of th e temporary

directory is defined by th e environment variable %TEMP%.

For more informa tion about th e installat ion pr ocess, read th e Installation

Guid e for PC, available in PDF format on th e Support page at Th e Math Works

Web site. Click on t he Documentat ion link an d go to the Online Manuals pageto find th e docum enta tion in PDF forma t.

Files Installed on PCs

This table lists the shared libraries (DLLs), include files, and other files

insta lled on a PC as par t of a MATLAB C/C++ Graphics Librar y insta llation.

In th e table, < ma t l a b > st an ds for your t op-level MATLAB inst allat ion

directory.

Note On PCs, th e MATLAB C/C++ Graph ics Libra ry inst allation includesnew versions of severa l sta nd ar d MATLAB dyna mic link libr ar ies (DLLs).

Table 1 -3 : List of Files Installed on PCs

Files Location Description

s g l . d l l

h g _ s g l . d l l

u i w _ s g l . d l l

h a r d c o p y _ s g l . d l l

g u i _ s g l . d l l

mp a t h . d l l

< ma t l a b > \ b i n Sha red librar ies containin g

st an d-alone versions of MATLAB

built -in a nd M-file graph ics

functions.

All DLLs are in WIN32 form at .

s g l

s g l c p p

< ma t l a b > \ b i n MATLAB Compiler bundle files,

containing all the compiler options

required to build a sta nd-alone

graph ics applicat ion.

8/8/2019 sgl_lib

14/57

1 Introduction

1-10

Verifying Your Installation

To verify th at th e MATLAB C/C++ Graphics Librar y ha s been inst alled

corr ectly, crea te a st an d-alone ap plicat ion from the exam ple M-file distribu ted

with th e library. Chapter 2, Creating Stand-Alone Graphics Applications

describes how to build a stand-alone application. You can find the graphicslibra ry example program in th e < ma t l a b > \ e x t e r n \ e x a mp l e s \ s g l directory.

Dow nloading a nd Installing on UN IX SystemsTo download and install the MATLAB C/C++ Graphics Library on a UNIX

system, follow these instructions:

1 Go to The Math Works Web site, www. ma t h wo r k s . c o m, an d click on t he

Downloads selection listed under Quick Links .

2 If you ha ve your License F ile, click on t he Download P roducts link . If you

do not h ave your License F ile, follow th e appr opriat e link to obta in it.

3 En ter your na me a nd MATLAB Access nu mber.

4 Select t he t ype of system on wh ich you wan t to ru n t he gra phics library from

th e list of supported system s, and t hen click th e Continue but ton. You canselect mu ltiple systems.

5 Select t he MATLAB C/C++ Gra phics Libra ry from t he list of produ cts you

ar e licensed to insta ll, an d th en click t he Continue button.

l i b s g l . h

l i b s g l m. h

s g l . d e f

< ma t l a b > \ e x t e r n \ i n c l u d e Graph ics library h eader files (. h )

an d modu le definition file (. d e f ).

F i g u r e Me n u Ba r . f i g

F i g u r e T o o l Ba r . f i g

< ma t l a b > \ e x t e r n \ i n c l u d e Alterna te men u bar an d toolbar files

used wit h t he MATLAB figur e

window in sta nd-alone applicat ions.

f l a me s . m

f l a me s . ma t

< ma t l a b > \ e x t e r n \ e x a mp l e s \ s g l The M-file and MAT file for the

graph ics libra ry example program .

Table 1 -3 : List of Files Installed on PCs (Continued)

8/8/2019 sgl_lib

15/57


1-11

6 Crea te a MATLAB ins ta llat ion dir ectory, if it doesnt a lrea dy exist, in your

root directory (for exam ple, / r o o t / ma t l a b ).

7 Download th e required pr oduct ar chives, an d a ny optiona l product a rchives,

into the MATLAB installation directory by right-clicking their links and

selecting t he sa ve option pr ovided by your browser. Do not chan ge the n am es

of th e ar chives.

8 In t he inst allation directory, extr act files from th e b o o t . f t p ar chive using

the UNIX t a r command

t a r - x v f b o o t . f t p

This archive contains a n inst aller progra m th at extracts files from the other

ar chives you downloaded.

9 Pla ce a copy of your License F ile in th e MATLAB inst allat ion dir ectory a nd

call it l i c e n s e . d a t .

10 Run th e MATLAB insta llation pr ogra m a nd follow th e instr uctions

pres ent ed on ea ch dialog box.

i n s t a l l _ ma t l a b - X

For more informa tion about th e installat ion pr ocess, read th e Installation

Guide for UN IX, available in PDF forma t on th e Support page at The

Math Works Web site. Click on t he Documentat ion link and go to th e Online

Manuals page to find th e docum enta tion in PDF form at .

Files Installed on UNIX Systems

This t able lists th e sha red libraries, include files, and other files inst alled on a

UNIX system as par t of a MATLAB C/C++ Graphics Librar y insta llat ion. In

the t able, < ma t l a b > st an ds for your t op-level MATLAB inst allat ion dir ectory.

8/8/2019 sgl_lib

16/57

1 Introduction

1-12

Table 1-4 : List of Files Installed on UN IX Systems

File Location Description

l i b mws g l . e x t ,

where . e x t is . s o on

Solaris systems an d

. s l on H P 700

systems

< ma t l a b > / e x t e r n / l i b / $ ARCH

where < ma t l a b > is th e na me of your

MATLAB root directory an d $ A RC H

identifies the system ar chitectur e

(i.e., a l p h a , l n x 8 6 , s g i , s g i 6 4 , s o l 2 )

The gra phics libra ry bina ry file.

The libraries ar e shar ed

libraries for all platforms.

s g l

s g l c p p

< ma t l a b > / b i n MATLAB Compiler bun dle files,

containing all the compiler

comm an d line options required

to build a st an d-alone graphics

application.

l i b s g l . h

l i b s g l m. h

< ma t l a b >/ e x t e r n / i n c l u d e The grap hics library h eader file

th at cont ains pr ototypes for boththe built-in and M-file graphics

functions.

F i g u r e Me n u Ba r . f i g

F i g u r e T o o l Ba r . f i g

< ma t l a b >/ e x t e r n / i n c l u d e Alternate m enu bar and toolbar

files used wit h t he MATLAB

figure window in st an d-alone

applications.

f l a me s . mf l a me s . ma t

< ma t l a b > / e x t e r n / e x a mp l e s / s g l The M-file an d MAT file for th egraph ics library example

program.

8/8/2019 sgl_lib

17/57


1-13

Verifying Your Installation

To verify th at th e MATLAB C/C++ Graphics Library h as been insta lled

corr ect ly, creat e a sta nd-alone app licat ion from the exam ple M-file dist ribu ted

with t he librar y. Chapter 2, Creating Stand-Alone Graphics Applications

describes how to build a stand-alone application. You can find the example

program in the < ma t l a b > / e x t e r n / e x a mp l e s / s g l directory.

8/8/2019 sgl_lib

18/57

1 Introduction

1-14

Configuring the M ATLAB C/ C++ Graphics Libra ryAfter inst alling t he MATLAB C/C++ Grap hics Librar y, you s hould configure it

using the mb u i l d - s e t u p comman d. When you r un mb u i l d , you s pecify:

The ANSI C or C++ compiler you int end t o use to compile the code gener at ed

by th e MATLAB Compiler

The libra ries you wan t t o link your a pplicat ion with ; specifically, the

MATLAB C/C++ Math Library a lone, or th e ma th librar y and th e MATLAB

C/C++ Graph ics Librar y together.

This section includes informa tion about :

Configurin g th e Gra phics Libra ry on PCs on pa ge 1-14

Configurin g th e Gra phics Libra ry on UN IX Syst ems on pa ge 1-16

For more informat ion about t he mb u i l d ut ility, see the MAT LAB Com piler

Users Gu ide. To learn how to build a st an d-alone graph ics a pplicat ion, seeChapter 2, Creating Stand-Alone Graphics Applications.

Configuring the Graphics Library on PCsTo configure t he gra phics librar y on a PC r un ning Microsoft Windows, run th e

mb u i l d - s e t u p comman d. You can ru n mb u i l d at th e MATLAB prompt or in a

DOS Comma nd P rompt window.

mb u i l d uses optionsfiles to specify all th e compile and lin k comm an d lineoptions necessary to create a sta nd-alone gra phics applicat ion u sing a

par ticular compiler. When you configure th e graph ics librar y, you determ ine

which options file mb u i l d uses t o creat e sta nd-alone a pplications.

When you ru n mb u i l d , you s pecify th e na me a nd version of th e compiler you

intend to use. mb u i l d locat es t he opt ions file specific to tha t compiler, an d

creat es a copy of it in your system s u ser p rofiles directory. From th en on,

when ever th e MATLAB Compiler calls mb u i l d to invoke your C or C++

compiler, it us es t his local copy of th e options file.

The following example illustr at es ru nn ing mb u i l d - s e t u p on a PC. The

examp le shows h ow to specify a compiler. If you h ave only one C or C++

compiler inst alled on your system, mb u i l d can determ ine its na me an d locat ion

au tomat ically. To link with th e graph ics library, ans wer yes (y ) a t t he mb u i l d

prompt.

8/8/2019 sgl_lib

19/57

Co nfiguring the M ATLAB C/ C ++ G raphics Library

1-15

mb u i l d - s e t u p

P l e a s e c h o o s e y o u r c o mp i l e r f o r b u i l d i n g s t a n d - a l o n e MAT L AB

a p p l i c a t i o n s .

Wo u l d y o u l i k e mb u i l d t o l o c a t e i n s t a l l e d c o mp i l e r s [ y ] / n ? n

Ch o o s e y o u r C/ C+ + c o mp i l e r :[ 1 ] Bo r l a n d C/ C+ + ( v e r s i o n 5 . 0 , 5 . 2 , o r 5 . 3 )

[ 2 ] Mi c r o s o f t Vi s u a l C/ C+ + ( v e r s i o n 4 . 2 , 5 . 2 , o r 6 . 0 )

[ 3 ] Wa t c o m C/ C+ + ( v e r s i o n 1 0 . 6 o r 1 1 )

[ 0 ] No n e

Co mp i l e r : 2

Ch o o s e t h e v e r s i o n o f y o u r C / C+ + c o mp i l e r :

[ 1 ] Mi c r o s o f t Vi s u a l C/ C+ + 4 . 2



v e r s i o n : 3

Yo u r ma c h i n e h a s a Mi c r o s o f t Vi s u a l C / C+ + c o mp i l e r l o c a t e d a t

D: \ P r o g r a m F i l e s \ De v S t u d i o 6 .

Do y o u wa n t t o u s e t h i s c o mp i l e r [ y ] / n ? y

Do y o u wa n t t o l i n k a g a i n s t t h e C/ C+ + Gr a p h i c s L i b r a r y [ y ] / n ? y

P l e a s e v e r i f y y o u r c h o i c e s :

Co mp i l e r : Mi c r o s o f t Vi s u a l C / C+ + 6 . 0

L o c a t i o n : D: \ P r o g r a m F i l e s \ De v S t u d i o 6

L i n k i n g a g a i n s t t h e C/ C+ + Gr a p h i c s L i b r a r y

Ar e t h e s e c o r r e c t ? ( [ y ] / n ) : y

1

8/8/2019 sgl_lib

20/57

1 Introduction

1-16

Configuring the G ra phics Libra ry on UN IX SystemsTo configure th e graph ics library on a UNIX system, run th e mb u i l d - s e t u p comma nd. You can r un mb u i l d at th e MATLAB prompt or at t he system

prompt.

mb u i l d uses optionsfiles to specify all th e compile and lin k comm an d line

options n ecessar y to create a sta nd-alone gra phics applicat ion. When you

configure t he gra ph ics librar y, you specify th e na me of th e options file you wan t

to use.

On UN IX systems, mb u i l d presen ts a choice of two opt ions files:

mb u i l d o p t s . s h and mb u i l d s g l o p t s . s h . To creat e a sta nd-alone gra phics

app licat ion, choose th e mb u i l d s g l o p t s . s h file (select ion 2). Whe n you select a n

options file, mb u i l d creates a local copy of the options file in your ~ / ma t l a b

directory.

Note Even t hough you select t he mb u i l d s g l o p t s . s h options file, whenmb u i l d creat es t he local copy in ~ / ma t l a b , it r enam es the file to

mb u i l d o p t s . s h .

The following example illustr at es ru nn ing mb u i l d on a UN IX syst em. To link

with t he gra phics libra ry, select option 2 . If you h ave ru n mb u i l d before , a local

copy of the opt ions file exists in your ~ / ma t l a b directory. When mb u i l d asks if

you want to overwrite th is existing version ofmb u i l d o p t . s h , answer yes (y ).

8/8/2019 sgl_lib

21/57

Co nfiguring the M ATLAB C/ C ++ G raphics Library

1-17


Us i n g t h e mb u i l d - s e t u p c o mma n d s e l e c t s a n o p t i o n s f i l e t h a t i s

p l a c e d i n ~ / ma t l a b a n d u s e d b y d e f a u l t f o r mb u i l d . An o p t i o n s

f i l e i n t h e c u r r e n t wo r k i n g d i r e c t o r y o r s p e c i f i e d o n t h e c o mma n d

l i n e o v e r r i d e s t h e d e f a u l t o p t i o n s f i l e i n ~ / ma t l a b .

Op t i o n s f i l e s c o n t r o l w h i c h c o mp i l e r t o u s e , t h e c o mp i l e r a n d l i n kc o mma n d o p t i o n s , a n d t h e r u n - t i me l i b r a r i e s t o l i n k a g a i n s t .

T o o v e r r i d e t h e d e f a u l t o p t i o n s f i l e , u s e t h e mb u i l d - f c o mma n d

( s e e mb u i l d - h e l p f o r mo r e i n f o r ma t i o n ) .

T h e o p t i o n s f i l e s a v a i l a b l e f o r mb u i l d a r e :

1 : / ma t l a b / b i n / mb u i l d o p t s . s h :Bu i l d a n d l i n k wi t h MAT L AB C/ C+ + Ma t h L i b r a r y

2 : / ma t l a b / b i n / mb u i l d s g l o p t s . s h :

Bu i l d a n d l i n k wi t h MAT L AB C/ C+ + Ma t h a n d Gr a p h i c s

L i b r a r i e s

E n t e r t h e n u mb e r o f t h e o p t i o n s f i l e t o u s e a s y o u r d e f a u l t o p t i o n s

f i l e : 2

1 I t d ti

8/8/2019 sgl_lib

22/57

1 Introduction

1-18

2

8/8/2019 sgl_lib

23/57

2

Crea t ing Stand-AloneGraph ics Applica t ions

Introduction . . . . . . . . . . . . . . . . . . . . 2-2

Overview . . . . . . . . . . . . . . . . . . . . . 2-3

Building a Stan d-Alone Graphics Application . . . . . 2-5

Building Graph ics Applicat ions on a PC . . . . . . . . . 2-5

Building Graph ics Applicat ions on a UNIX System . . . . . 2-7

Runn ing th e MATLAB Compiler Outs ide MATLAB . . . . 2-9

Chan ges in Run-time Behavior an d Appear an ce . . . . . . 2-10

Pack aging a Graphics Application for Redistribution . 2-13Pa ckaging Graph ics Applicat ions on a PC . . . . . . . . 2-13

Pa ckaging Graph ics Applicat ions on a UNIX System . . . . 2-14

Compil ing and Linking Translated M-Files . . . . . . 2-15

Compiling Tran slated M-Files . . . . . . . . . . . . . 2-15

Link ing with MATLAB Libra ries . . . . . . . . . . . . 2-15

2 Creating Stand-Alone Graphics Applications

8/8/2019 sgl_lib

24/57


2-2

IntroductionAfter inst alling an d configur ing th e MATLAB C/C++ Grap hics Librar y,

described in Chapt er 1, Int roduction, you can use it to creat e sta nd-alone

gra phics applications. This cha pt er includes t he following topics:

Overview on p age 2-3

Building a Sta nd -Alone Gr aph ics Applicat ion on page 2-5

Pa ckaging a Gra ph ics Applicat ion for Redistr ibut ion on p age 2-13

Comp iling an d Link ing Tra ns lat ed M-Files on page 2-15

O verview

8/8/2019 sgl_lib

25/57

O verview

2-3

OverviewTo crea t e a st an d-alone C or C++ gra ph ics ap plicat ion, use t he MATLAB

Compiler (mc c ). The MATLAB Compiler :

Tra ns lat es th e specified M-file int o a C or C++ sour ce code module

Gener at es add itiona l C or C++ source code modules, called wrapperfiles,

required by st an d-alone a pplicat ions

Compiles and link s t he source modules into a sta nd-alone a pplicat ion, by

invoking your ANSI C or C++ compiler a nd lin ker .

Figure 2-1 shows how the Compiler works in conjun ction with oth er t ools a nd

libraries to create a sta nd-alone gra phics applicat ion. In th e figure, each tool is

represent ed by a sha dowed box. For more deta iled informa tion about u sing th e

MATLAB Compiler and the mb u i l d ut ility, see th e MAT LA B Com piler Users

Guide.

Note Do not confuse t he MATLAB Compiler with an ANSI C or C++compiler. The MATLAB Compiler t ra ns lat es M-code int o C or C++ sour ce code,

which can t hen be compiled into object modules u sing a n ANSI C or C++

compiler. This docum ent at ion dist ingu ishes r eferen ces to th e MATLAB

Compiler by usin g th e word Compiler with a capit al C. References to

comp iler with a lower case c refer t o your ANSI C or C++ compiler.

Note tha t a st an d-alone gra phics applicat ion mu st be linked with several

MATLAB librar ies as well as a n ANSI C/C++ ma th librar y. The MATLAB API

an d MAT-file librar ies come wit h MATLAB. The MATLAB Math Built-In

Library a nd t he MATLAB M-File Math Library a re component s of th e

MATLAB C/C++ Math Libra ry.


8/8/2019 sgl_lib

26/57

g p pp

2-4

Figure 2 -1 : Crea ting a Stand-Alone C or C++ Graphics Applica tions

M-file tha t includes

graphics functions

MATLAB Comp iler

C or C++ sour ce fileversion of M-file

C or C++ compiler

Object files

Linker

Sta nd-alone C or C++

graphics application

MATLAB M-File Mat h Libra ry

MATLAB Mat h Built-In Library

MATLAB API Libra ry

MATLAB MAT-File Library

ANSI C or C++ Librar y

MATLAB C/C++ Gra phics Libra ry

Building a Stand-Alone Graphics Application

8/8/2019 sgl_lib

27/57

Building a Stand Alone Graphics Application

2-5

Building a Stand-Alone Graphics ApplicationThe best way to learn how to build a sta nd-alone gra phics applicat ion is t o see

an example. This section shows how to creat e a st an d-alone gra phics

ap plicat ion by convert ing one of th e demo progra ms in clud ed with MATLAB,

l o r e n z . m. This demo plots t he orbit of a point a round t he Lorenz cha otic

at tr actor. (For more informa tion about t he Lorenz applicat ion, type h e l p

l o r e n z at th e MATLAB prompt .) This demo is a useful exam ple becau se it u ses

graph ics functions an d includes several u ser-int erface objects, su ch as push

buttons.

This section includes:

Building Gr ap hics Applications on a P C on pa ge 2-5

Building Gr ap hics Applicat ions on a U NIX System on page 2-7

Changes in Run-time Behavior and Appearance on page 2-10

Building Graphics Applications on a PCThe following code examp le convert s th e Loren z applicat ion int o a sta nd-alone

applicat ion on a PC. To tr y th is example, start MATLAB and perform th ese

steps a t t he MATLAB prompt. You can also creat e a st an d-alone graphics

applicat ion with run ning MATLAB. For informa tion, see Running the

MATLAB Compiler Outside MATLAB on page 2-9.


! c o p y \ t o o l b o x \ ma t l a b \ d e mo s \ l o r e n z . m * . *

mc c - B s g l l o r e n z . m

! l o r e n z

Note th e following:

The example uses mb u i l d - s e t u p to set up the environment t o creat esta nd-alone a pplicat ions. This st ep is only required t he first time you creat e

a st an d-alone graphics applicat ion. For deta iled inform at ion a bout ru nn ing

mb u i l d , see Configurin g th e MATLAB C/C++ Graph ics Libra ry on pa ge

1-14.


8/8/2019 sgl_lib

28/57

2-6

The example uses th e DOS c o p y comm an d to copy th e Loren z application

M-file int o the cur ren t MATLAB directory. < ma t l a b > represents your

toplevel MATLAB directory. (This s tep is suggest ed because you m ay n ot

ha ve permiss ion t o crea te a n ew file in t he MATLAB d e m o s dir ectory.) You

can also u se Microsoft Windows Explorer to copy t he file.

The exam ple invokes t he MATLAB Compiler , using th e - B flag t o specify t he

graph ics libra ry bundle file. Bundle files ar e ASCII t ext files th at cont ain

Compiler comma nd line options a nd a rgumen ts. The s g l bun dle file,

specified in th e example, crea tes a C st an d-alone ap plicat ion. To creat e a C++applicat ion, use t he s g l c p p bund le file. The bu ndle files reside in t he

< ma t l a b > \ b i n directory.

Note Do not u se th e Compiler - V1 . 2 flag when creating a sta nd-alonegraphics library.

Results of Compilation

When it tr an slates an M-file applicat ion, th e MATLAB Compiler genera tes

mu ltiple C or C++ source code modu les in your curr ent working directory.

These include wrapperfiles that contain necessary components of a

sta nd-alone a pplication, such as a ma i n ( ) entry point.

In a ddition, th e first time you ru n t he MATLAB Compiler t o creat e a

sta nd-alone gra phics applicat ion, it creates a subdirectory, nam ed \ b i n , inyour cur rent work ing directory. The Compiler pu ts in t his directory versions of

th e MATLAB menu bar a nd t oolbar figure files tha t a re us ed by stan d-alone

graph ics a pplicat ions at ru n-time. (For more inform at ion, see Cha nges in

Run-time Behavior and Appearance on page 2-10 .) When you r un th e

Compiler s ubs equen tly, it checks for th e exist ence of th ese files and does not

overwrite t hem if th ey exist.

Running a Stand-Alone Graphics ApplicationThe Compiler creates t he st an d-alone graphics applicat ion a s an execut able

progra m in your cur rent work ing directory, giving it t he sa me na me as your

M-file but with t he . e x e filena me extension. You can r un th e applicat ion a t t he

MATLAB comm an d prompt if you pr ecede th e na me wit h a ! symbol, as shown

in th e example. You can also run sta nd-alone gra phics app licat ions out side the


8/8/2019 sgl_lib

29/57

2-7

MATLAB environm ent. However, mak e sure t ha t t he directory cont aining t he

sha red libraries t o which your app licat ion h as been linked (< ma t l a b > \ b i n ) ison your directory search pat h.

Editing the Search Path on Windows 95. On Window95 systems, you m ust edit your

a u t o e x e c . b a t file to add your sha red library directory to the P A T H variable.

Editing the Search Path on Windows NT. On Windows NT systems, go th e Sett ings

option on th e Start menu an d choose Control Pan el . Double-click on t he

System icon to view th e System Propert ies dialog box. Use th e En vironm entpanel to edit t he P A T H variable.

Building Gra phics App lica tions on a UN IX SystemThe following code exam ple convert s th e Loren z applicat ion int o a st an d-alone

applicat ion on a UNIX system. To tr y th is example, start MATLAB an d

perform th ese steps at th e MATLAB prompt. You can also creat e a st and -alone

graph ics a pplicat ion with ru nn ing MATLAB. For informa tion, see Running

th e MATLAB Compiler Ou ts ide MATLAB on pa ge 2-9.


! c p < ma t l a b > / t o o l b o x / ma t l a b / d e mo s / l o r e n z . m . /

mc c - B s g l l o r e n z . m

! l o r e n z

Note th e following:

The example uses mb u i l d - s e t u p to set up the environment t o creat e

sta nd-alone a pplicat ions. This st ep is only required t he first time you creat e

a st an d-alone graphics applicat ion. For deta iled inform at ion a bout ru nn ing

mb u i l d , see Configurin g th e MATLAB C/C++ Graph ics Libra ry on pa ge

1-14.

The exam ple uses th e UNIX c p comm an d to copy th e Loren z application

M-file into th e curr ent MATLAB directory. Use t he ! symbol to execut e an

operat ing system comma nd inside th e MATLAB environm ent. (This step is

suggested becau se you m ay not h ave permission t o creat e a n ew file in t he

MATLAB d e m o s directory.) < ma t l a b > repr esent s your toplevel MATLAB

directory.


8/8/2019 sgl_lib

30/57

2-8

The exam ple invokes t he MATLAB Compiler, u sing th e - B flag t o specify t he

graph ics libra ry bundle file. Bundle files ar e ASCII t ext files th at cont ain

Compiler comma nd line options a nd a rgum ents. The s g l bun dle file,

specified in th e example, crea tes a C st an d-alone ap plicat ion. To creat e a C++

applicat ion, use t he s g l c p p bund le file. The bu ndle files reside in t he

< ma t l a b > / b i n directory.

Note Do not use th e - V1 . 2 flag when us ing th e MATLAB Compiler to crea tea s ta nd-alone gra phics librar y.

Results of Compilation

When it tr an slat es an M-file applicat ion, th e MATLAB Compiler generat es

mu ltiple C or C++ source code modules in your cur ren t workin g directory.

These include wrapperfiles that contain necessary components of a

sta nd-alone a pplication, such as a ma i n ( ) entry point.

In a ddition, th e first time you ru n t he MATLAB Compiler t o creat e a

sta nd-alone gra phics applicat ion, it creates a subdirectory, nam ed / b i n , in

your cur rent work ing directory. The Compiler pu ts in t his directory versions of

th e MATLAB menu bar a nd t oolbar figure files tha t a re us ed by stan d-alone

graph ics a pplicat ions at ru n-time. (For more inform at ion, see Cha nges in

Run-time Behavior and Appearance on page 2-10 .) When you r un th e

Compiler s ubs equen tly, it checks for th e exist ence of th ese files and does not

overwrite t hem if th ey exist.

Running a Stand-Alone Graphics Application

The Compiler creates t he st an d-alone graphics applicat ion a s an execut able

progra m in your curr ent work ing directory, giving it t he sa me na me as your

M-file. You can ru n your st an d-alone gra phics applicat ion a t t he MATLAB

prompt if you pr ecede the execut able nam e with a !, as shown in t he example.

You can also run a st an d-alone a pplication outs ide of th e MATLAB

environm ent. However, you m ust add t o your pat h t he locat ion of th e shar ed


8/8/2019 sgl_lib

31/57

2-9

libra ries to which your a pplicat ion is linked. To set your pa th , use th e

command from t his t able th at is specific for your system.

To avoid ha ving to reissue this comma nd a t t he st ar t of each login session,

include it in a st art up script su ch a s ~ / . c s h r c o r ~ / . l o g i n . Use the ~ / . l o g i n

option, if your system sup ports it , becau se it only gets executed once.

Running the M ATLAB Com piler O utside M ATLABYou can ru n t he MATLAB Compiler wit hout also run nin g MATLAB. However,

if you d o, you m ust specify th e locations of th e M-files th at your app licat ion

depends on, using th e - I option on th e Compiler comm an d line. When you r un

th e Compiler from with in MATLAB, it can locate t hese files by referencing th e

MATLAB path.

For example, the Lorenz applicat ion u ses fun ctions in th e g r a p h 2 d , g r a p h i c s ,

d e m o s , and g r a p h 3 d su bdirectories of th e < ma t l a b > / t o o l b o x / ma t l a b/ dir ectory.

A convenient way to provide the Compiler with th is pat h informa tion is to star t

MATLAB and run the mc c s a v e p a t h comma nd. Th is comm an d creates a file in

your cur rent working directory, na med mc c p a t h , that conta ins this path

inform at ion. When you r un th e Compiler outside t he MATLAB environm ent, it

au toma tically looks for t his pa th inform at ion file in your local directory.

Architecture Command

HP700 s e t e n v S HL I B_ P AT H < ma t l a b > / e x t e r n / l i b / h p 7 0 0 : < ma t l a b > / b i n /

h p 7 0 0 : $ S HL I B_ P AT H

All oth ers s e t e n v L D_ L I BRAR Y_ P AT H < ma t l a b > / e x t e r n / l i b / < a r c h > : < ma t l a b > / b i n /

< a r c h > : $ L D_ L I BRARY_ P AT H

where:

< ma t l a b > is the MATLAB root directory.

< a r c h > is your a rchitectu re (i.e., alpha , lnx86, sgi, sgi64, sol2).


8/8/2019 sgl_lib

32/57

2-10

Changes in Run-time Behavior and AppearanceStand-alone versions of graphics applications typically look and operate the

sam e as t heir M-file counterpa rt s. Note, however, tha t becau se sta nd-alone

applicat ions r un out side the MATLAB environmen t, some sta nda rd MATLAB

menu bar options ar e not support ed. For example, sta nd-alone app licat ions

cann ot sup port plot editin g or p rovide access t o MATLAB Help files.

To illustrate these differences, compare Figure 2-2, which sh ows th e Lorenz

applicat ion r un ning a s an M-file on a P C, with Figure 2-3, which sh ows t he

Lorenz a pplicat ion r un ning a s a sta nd-alone a pplicat ion. These differences arediscussed in th e following sections:

Cha nges t o Figure Window Menu Op tions on page 2-11

Chan ges to Default Prin t Ha ndling on page 2-11

Includin g Help in a Sta nd -Alone Gr aph ics Applicat ion on p age 2-12

Ctr l-C Ha ndlin g on pa ge 2-12

Figure 2 -2 : M-File Version of the Lorenz Application


8/8/2019 sgl_lib

33/57

2-11

Figure 2 -3 : Stand-Alone Version of the Lorenz Application

Changes to Figure Window Menu Options

In st an d-alone graph ics applicat ions, th e Figure window menu ba r cont ains

only th e File menu option. Sta nd-alone grap hics applicat ions r un without

MATLAB and can not sup port ma ny of th e options available thr ough t he Edit ,

Tools , and Help menu s, such as plot editing. When you creat e a st an d-aloneapplicat ion, th e graphics librar y excludes th ese items from t he men u ba r.

The gra phics librar y also excludes options from t he File menu, such as t he

Property Editor and Page Setup options, tha t a re not supported by

sta nd-alone applicat ions.

Changes to Default Print Handling

Becau se stan d-alone gra phics applicat ions su pport print ing, th e Figure

window File menu includes the Prin t option. This option executes the p r i n t

comman d setu p when th e applicat ion wa s created in MATLAB. For

inform at ion a bout th e various pr int options supported by the gra phics libra ry,

see Graph ics Librar y Pr inting Support on page 1-3.


8/8/2019 sgl_lib

34/57

2-12

Note, however, tha t t he Print option in sta nd-alone gr aph ics a pplicat ions does

not display th e Prin t dialog box, as it does for M-file applications.

Including Help in a Stand-Alone Graphics Application

When you pr ess the Info but ton in t he M-file version of th e Loren z application,

it displays a separa te h elp window cont aining t he M-file help for t he Lorenz

fun ction. I f you click on th e Info butt on in t he sta nd-alone version of th e Lorenz

applicat ion, you get t he err or message:

An e r r o r o c c u r r e d i n t h e c a l l b a c k : l o r e n z ( i n f o )T h e e r r o r me s s a g e c a u g h t wa s : F u n c t i o n " h e l p wi n " i s n o t

s u p p o r t e d i n s t a n d a l o n e a p p l i c a t i o n s

St an d-alone a pplications do not ha ve access to MATLAB help.

Ctrl-C Handling

When you ru n a graph ics ap plicat ion with in MATLAB, you can press Ctrl-C to

brea k infinite loops. For exam ple, you can p ress Ctrl-C to stop an animat ion.When you ru n a C or C++ sta nd-alone a pplicat ion, Ctrl-C ha ndling is not

supported.

Packa ging a G raphics App lication for Redistribution

8/8/2019 sgl_lib

35/57

2-13

Packaging a Graphics Application for Redistribution

To distribut e a st an d-alone graphics applicat ion, you m ust creat e a pa cka ge

th at includes th e applicat ions execut able as well as t he sh ared librar ies

against which th e applicat ion wa s linked. This section d escribes:

Pa ckaging Gra ph ics Applicat ions on a P C on page 2-13

Pa ckaging Gra ph ics Applicat ions on a UN IX Syst em on page 2-14

Pack a ging Gra phics Applica tions on a PCWhen pa ckaging an applicat ion for r edistribut ion on a P C, you must include

th ese librar ies along with your applicat ion execut able:

< ma t l a b > \ b i n \ s g l . d l l

< ma t l a b > \ b i n \ h g _ s g l . d l l

< ma t l a b > \ b i n \ u i w _ s g l . d l l

< ma t l a b > \ b i n \ g u i _ s g l . d l l

< ma t l a b > \ b i n \ h a r d c o p y _ s g l . d l l

< ma t l a b > \ b i n \ mp a t h . d l l

< ma t l a b > \ b i n \ l i b mmf i l e . d l l

< ma t l a b > \ b i n \ l i b ma t . d l l

< ma t l a b > \ b i n \ l i b mc c . d l l

< ma t l a b > \ b i n \ l i b ma t l b . d l l

< ma t l a b > \ b i n \ l i b mx . d l l

< ma t l a b > \ b i n \ l i b u t . d l l

When pa ckaging a sta nd-alone a pplicat ion, also remember to include:

The ANSI C or C++ libra ries you linked with your app licat ion

Th e \ b i n directory a ssociated with your sta nd-alone applicat ion. See

Results of Compilation on page 2-6 for m ore informa tion about th is

directory.

All dynamic link libraries (DLLs) associated with your application must be

on t he system pat h. You m ust either install them in a directory that is

already on the pa th or modify the %PATH% variable, as p art of your applicat ion

insta llat ion procedure, t o include t he new directory.


8/8/2019 sgl_lib

36/57

2-14

Pa ck a ging Gra phics Applica tions on a UN IX SystemWhen pa ckaging an applicat ion for r edistribut ion on a UNIX system, you m ust

include t hese libraries with your applicat ion execut able. In th e filenam es in

this list, the . e x t is . s o on Solaris, Alpha , Linux, an d SGI; and . s l on H P 700.

< ma t l a b > / e x t e r n / l i b / < a r c h > / l i b mws g l . e x t

< ma t l a b > / e x t e r n / l i b / < a r c h > / l i b ma t . e x t

< ma t l a b > / e x t e r n / l i b / < a r c h > / l i b mi . e x t

< ma t l a b > / e x t e r n / l i b / < a r c h > / l i b mmf i l e . e x t

< ma t l a b > / e x t e r n / l i b / < a r c h > / l i b mc c . e x t

< ma t l a b > / e x t e r n / l i b / < a r c h > / l i b ma t l b . e x t

< ma t l a b > / e x t e r n / l i b / < a r c h > / l i b mx . e x t

< ma t l a b > / e x t e r n / l i b / < a r c h > / l i b u t . e x t

< ma t l a b > / b i n / < a r c h > / l i b mwh g . e x t

< ma t l a b > / b i n / < a r c h > / l i b mwu i x . e x t

< ma t l a b > / b i n / < a r c h > / l i b mwg u i . e x t

< ma t l a b > / b i n / < a r c h > / l i b mwh a r d c o p y . e x t < ma t l a b > / b i n / < a r c h > / l i b mwmp a t h . e x t

When pa cka ging a sta nd-alone a pplicat ion, also remem ber to include:

The ANSI C or C++ libra ry you link ed with your a pplicat ion

The cont ent s of th e / b i n directory ass ociated with your sta nd-alone

application . See Results of Compilation on page 2-8 for m ore inform at ion

about t his directory.

C omp iling a nd Linking Translated M -Files

8/8/2019 sgl_lib

37/57

2-15

Compiling and Linking Translated M-Files

It is possible to build a sta nd-alone a pplicat ion with out u sing mb u i l d . You mu st

st ill use th e MATLAB Compiler to gener at e C or C++ sour ce code modules.

However, after t ha t, you can compile and link th ese modules as you would an y

application.

Compiling Translated M-Files

Compile the gener at ed C or C++ source files with a n ANSI C or C++ comp iler.You m ust ma ke sur e the include file search pat h includes the directory in

which t he file ma t l a b . h resides. ANSI C or C++ compilers t ypically use t he - I

switch t o add directories to th e include file sear ch pat h.

Link ing w ith M ATLAB Libra riesLink t he r esulting object files agains t t hese libraries:

MATLAB C/C++ Gra phics Libra ry (l i b mws g l )

MATLAB M-File Mat h Libr ar y (l i b mmf i l e )

MATLAB Mat h Built-In Library ( l i b ma t l b )

MATLAB MAT-File Library (l i b ma t )

MATLAB API Libra ry (l i b mx )

ANSI C or C++ ma th library (l i b m)

On PCs. For a complete list of the librar ies required for graph ics a pplicat ions,an d th e order in wh ich t hey should be specified, sta rt MATLAB and r un th e

mb u i l d - s e t u p comman d. When mb u i l d deter min es th e C or C++ compiler you

int end t o use, it creat es an options file for th at compiler, called c o mp o p t s . b a t ,

th at lists all th e librar ies, in t he corr ect order. You can find t he c o mp o p t s . b a t

file in a su bdirectory of the u ser pr ofiles directory.


8/8/2019 sgl_lib

38/57

2-16

Note If you ar e usin g the Microsoft Visual C compiler, you m us t m an ua llybuild import librar ies from th e . d e f files u sing th e l i b comm an d. If you a re

using t he Borland C compiler, you can link directly against th e . d e f files

using the i mp l i b comm an d. If you a re u sing t he Wat com C compiler, you mu st

build the import libraries from t he DLLs using the wl i b comm an d. See your

compiler docum ent at ion for inform at ion about th ese comma nds.

On UNIX Systems. To see a complete list of th e librar ies requir ed for gra phics

applications, view the mb u i l d s g l o p t s . s h file in < ma t l a b > / b i n . Search for t he

section of th is file specific to your syst em a rchitectu re. The comm an d lists t he

required libraries, specified in the correct order.

3

8/8/2019 sgl_lib

39/57

Troubleshooting

Introduction . . . . . . . . . . . . . . . . . . . . 3-2

Using Uns upported MATLAB 5.3 Feat ures . . . . . . . . 3-2

Compiling Applicat ion Writt en as Scripts . . . . . . . . . 3-3Fixing Callback Pr oblems: Illegal Synta x . . . . . . . . . 3-4

Fixing Callback Pr oblems: Missing Fun ctions . . . . . . . 3-7

Depending on Graph ics Settin gs in Sta rt-Up Files . . . . . 3-9

Pr int Option Does Not Appear on File Menu . . . . . . . 3-9

3 Troubleshooting

8/8/2019 sgl_lib

40/57

3-2

Introduction

The MATLAB Compiler can compile most M-files th at use gr aph ics int o

st an d-alone a pplicat ions. Some M-files, however, m ay include coding pr actices

th at are n ot su pported by the Compiler or by the gra phics library. In some

cases, the MATLAB Compiler m ay n ot be able to tra ns lat e th e M-file into C or

C++ code. In other cases , th e M-file ma y compile successfully but fail when ru n

as st an d-alone application.

This chapt er describes how to diagnose and correct th ese problems, including:

Usin g Uns up ported MATLAB 5.3 Feat ur es on page 3-2

Compiling Application Writ ten as Scripts on pa ge 3-3

Fixing Ca llback Pr oblems: Illegal Synt ax on page 3-4

Fixing Ca llback Pr oblems: Missing F un ctions on p age 3-7

Depending on Graphics Settings in Start-Up Files on page 3-9

Pr int Opt ion Does Not Appear on F ile Menu on page 3-9

Using Unsupported MATLAB 5.3 FeaturesThe MATLAB Compiler s up ports m ost of th e MATLAB 5.3 lan gua ge feat ur es,

including multidimens iona l arra ys, cell arr ays, and st ru ctu res. However, th e

Compiler does not su pport:

The MATLAB e v a l or i n p u t command

MATLAB objects

MATLAB int eger types ( i n t 8 , i n t 1 6 , i n t 3 2 , u i n t 8 , u i n t 1 6 , and u i n t 3 2 )

See the MAT LA B Com piler Users Guid e for m ore inform at ion a bout th ese

limitations.

Symptom

The Compiler out put s error messages tha t identify which u nsu pported featu re

prevented compilation.

Workaround

If your applicat ion u ses un support ed featu res, the only worka round is t o

remove these u nsu pport ed feat ur es by recoding your applicat ion.

Introduction

8/8/2019 sgl_lib

41/57

3-3

Compiling Applications Written as ScriptsThe Compiler can not compile applicat ions writt en a s scripts becaus e scripts

intera ct with th e MATLAB base workspace and st an d-alone applicat ions do

not h ave access t o th e MATLAB bas e work spa ce.

Symptom

If you a tt empt to compile a script, t he Compiler output s th e error message

? ? ? E r r o r : F i l e f i l e n a me i s a S c r i p t M- f i l e a n d c a n n o t b e

c o mp i l e d wi t h t h e c u r r e n t Co mp i l e r .

where f i l e n a me is th e na me of your script M-file.

Workaround

To compile an applicat ion wr itten as a script, t ur n it into a MATLAB fun ction.

To do th is, includ e th e MATLAB fun ction prototype a t t he t op of the file. You

mu st a lso find where t he script depends on variables in th e base worksp ace and

declare t hese varia bles a s global variables.

For exam ple, in t he following script, th e varia ble f , set by the call to the f i g u r e

fun ction, exists in th e base workspace. This variable is th en pa ssed as a

parameter to the function, my _ f u n c , specified in th e callback propert y str ing.

Pa ssing a workspa ce variable in a callback st ring is su pported in MATLAB but

it is not su pport ed by the MATLAB Compiler.

f = f i g u r e ;

p _ b t n = u i c o n t r o l ( g c f , . . .

' s t y l e ' , p u s h b u t t o n ' , . . .

' P o s i t i o n ' , [ 1 0 1 0 1 3 3 2 5 ] , . . .

' S t r i n g ' , ' P r e s s He r e ' , . . .

' Ca l l B a c k ' , ' my _ f u n c ( f ) ; ' ) ;

The following example shows t his script t ra nsformed into a fun ction.

f u n c t i o n wa s _ a _ s c r i p t ( )% n e w f u n c t i o n

g l o b a l f ;

f = f i g u r e ;

3 Troubleshooting

8/8/2019 sgl_lib

42/57

3-4

p _ b t n = u i c o n t r o l ( g c f , . . .' s t y l e ' , p u s h b u t t o n ' , . . .

' P o s i t i o n ' , [ 1 0 1 0 1 3 3 2 5 ] , . . .

' S t r i n g ' , ' P r e s s He r e ' , . . .

' Ca l l B a c k ' , ' my _ c a l l b a c k ) ;

In t his code exam ple, note th e following:

The exam ple cha nges t he s cript into a fun ction by including a MATLAB

function pr otot ype line a t t he t op of th e file.

The example declares t he var iable f , former ly referen ced in t he ba se

workspa ce, as a global var iable. This ma kes it a ccessible to the callback

routine.

The example replaces the r eference to my _ f u n c in th e callback str ing with th e

na me of a n ew fun ction, my _ c a l l b a c k . This new function p erform s t he

processing formerly done in the callback string.

Her e is the n ew callback function. Note how the function also declar es f as

a global variable.

f u n c t i o n my _ c a l l b a c k ( )

% r e v i s e d c a l l b a c k

g l o b a l f ;

my _ f u n c ( f ) ;

Fix ing Ca llba ck Problem s: Illega l SyntaxWhen a u ser clicks on an intera ctive element in a u ser int erface, such as a pu sh

butt on, MATLAB parses th e text str ing associated with t he c a l l b a c k property

of th e element an d execut es the comm an ds contained in t his str ing. The

callback pa rser th at comes with t he MATLAB C/C++ Graphics Library

support s a subset of M syntax su pport ed by the MATLAB int erpret er.For exam ple, both th e MATLAB callback pa rser an d t he gra phics librar y

callback par ser su pport th ese const ructs in callback st rings:

Nesting function calls

Passing scalar a rguments

Introduction

8/8/2019 sgl_lib

43/57

3-5

Passing string argument s

Passing non-nested array argument s

Specifying ra nges

This sam ple callback st ring illust rat es a n ested function call, g c a ; a string

constant, c o l o r ; a vector const an t [ 0 0 1 ] ; and a simple ran ge, 0 : . 2 : 1 .

s e t ( g c a , c o l o r , [ 0 0 1 ] , x t i c k , 0 : . 2 : 1 )

These const ructs, which ar e support ed in MATLAB, are notsupported by th e

graph ics library callback par ser:

Passing mu ltidimensional arr ays as function argument s

Referencing workspace variables

Making assignmen ts t o work space var iables

Performin g mat h operations, such a s addition or subt ra ction

SymptomYour M-file application compiles s uccessfully, crea tin g a s ta nd-alone

execut able. However, when you r un it, intera ctive user interface element s,

such as a push but ton, are not responsive. When you exit th e applicat ion, the

graph ics libra ry issues an error message such as:

An e r r o r o c c u r r e d i n t h e c a l l b a c k : c o l o r ma p ( [ 1 1 1 ; 0 0 0 ] ) ;

T h e e r r o r me s s a g e c a u g h t wa s : Co l o r ma p mu s t h a v e 3 c o l u mn s :

[ R, G, B] .

Workaround

To fix an a pplicat ion t hat includes an y of these const ru cts in a callback st ring:

Search t he a pplicat ion M-file for th e callback str ing associated with th e

callback p roperty of the u nresponsive user interface element . For

inform at ion about finding callback st rings, see Finding Callback Str ings in

an M-File on pa ge 3-7.

Remove the callback string from the M-file, if it uses unsupported

programm ing constru cts, an d put it int o a new M-file, using it as t he basis

for a new fun ction.

Specify th e na me of this new function a s t he valu e of th e callback st ring

associated with t he user inter face element.

3 Troubleshooting

8/8/2019 sgl_lib

44/57

3-6

For example, this gra phics ap plicat ion displays t he outpu t of the p e a k s

fun ction and includes a push butt on t ha t chan ges the colorma p to black andwhite.

f u n c t i o n my _ t e s t ( )

% Gr a p h i c s l i b r a r y c a l l b a c k t e s t a p p l i c a t i o n

p e a k s ;



' P o s i t i o n ' , [ 1 0 1 0 1 3 3 2 5 ] , . . .

' S t r i n g ' , ' Ma k e B l a c k & Wh i t e ' , . . .

' C a l l B a c k ' , ' c o l o r ma p ( [ 1 1 1 ; 0 0 0 ] ) ; ' ) ;

This M-file compiles successfully, crea tin g a st an d-alone a pplicat ion. H owever,

when you r un it, th e push butt on d oesnt cha nge th e color map . When you close

th e applicat ion, the grap hics libra ry issues th e error message:

An e r r o r o c c u r r e d i n t h e c a l l b a c k : c o l o r ma p ( [ 1 1 1 ; 0 0 0 ] ) ;

T h e e r r o r me s s a g e c a u g h t wa s : Co l o r ma p mu s t h a v e 3 c o l u mn s :

[ R, G, B ] .

This error is generat ed because th e arra y argument passed to the c o l o r ma p

function, [ 1 1 1 ; 0 0 0 ] , conta ins more t ha n one row. To fix th is application,

creat e a new fun ction th at contains t he call to c o l o r ma p :

f u n c t i o n c h a n g e _ c o l o r ma p ( )

% Ne w f u n c t i o n ma d e f r o m c a l l b a c k p r o p e r t y s t r i n g

c o l o r ma p ( [ 1 1 1 ; 0 0 0 ] ) ;

Then, in th e app licat ion M-file, replace the callback s tr ing associated with th e

push butt on with t he na me of th e new fun ction, c h a n g e _ c o l o r ma p :



%# f u n c t i o n c h a n g e _ c o l o r ma p

p e a k s ;


Introduction

8/8/2019 sgl_lib

45/57

3-7


' P o s i t i o n ' , [ 1 0 1 0 1 3 3 2 5 ] , . . .' S t r i n g ' , ' Ma k e B l a c k & Wh i t e ' , . . .

' Ca l l B a c k ' , ' c h a n g e _ c o l o r ma p ' ) ;

This m odified M-file successfully compiles an d, when execut ed as a st an d-alone

applicat ion, th e push bu tt on operates a s expected.

This example a lso includes a call to th e %# f u n c t i o n pragma. This pragma lists

fun ctions t ha t you want th e Compiler to compile. This is required if a function

is specified only in a callback st rin g an d not a nywh ere else in an M-file. Whenpr ocessing a n M-file, th e Compiler d eter min es which functions a n M-file

depen ds on an d compiles t hem all. The Compiler does not check th e callback

str ings for fun ctions. For more informat ion a bout th is pragma , see Fixing

Callback Pr oblems: Missing Fu nctions on page 3-7.

Finding Callback Strings in an M-File

To find callback st rin gs in a n M-file, search your M-file for th e char acter

strings Ca l l b a c k or F c n . This will find a ll th e Ca l l b a c k properties defined byHandle Graphics objects, such a s u icont rol and u imenu . In ad dition, th is will

find t he pr opert ies of figures an d axes th at end in F c n , such as

Cl o s e R e q u e s t F c n , tha t a lso support callbacks.

Fix ing Ca llba ck Problem s: M issing FunctionsWhen the Compiler creates a stand-alone application, it compiles the M-file

you sp ecify on th e comma nd line a nd, in a ddition, it compiles a ny oth er M-filesth at your M-file calls. If your a pplicat ion in clud es a call to a function in a

callback str ing or in a st ring passed as an argument to the f e v a l fun ction or

an ODE solver, and t his is t he only place in your M-file th is fun ction is called,

th e Compiler will not compile t he fun ction. Th e Compiler d oes not look in th ese

text str ings for fun ctions t o compile.

Symptom

Your applicat ion ru ns but an intera ctive user interface element, such as a pushbut ton, is un responsive. When you close t he a pplicat ion, th e graph ics library

issues this error message:

An e r r o r o c c u r r e d i n t h e c a l l b a c k : c h a n g e _ c o l o r ma p

T h e e r r o r me s s a g e c a u g h t wa s : R e f e r e n c e t o u n k n o wn f u n c t i o n

c h a n g e _ c o l o r ma p f r o m F EVAL i n s t a n d - a l o n e mo d e .

3 Troubleshooting

8/8/2019 sgl_lib

46/57

3-8

Workaround

To eliminat e th is error, creat e a list all of th e functions t ha t ar e specified onlyin callback str ings and pa ss th is list t o th e %# f u n c t i o n pra gma. (See Finding

Missing Fu nctions in a n M-File on page 3-8 for hint s a bout finding functions

in callback str ings.) The Compiler pr ocesses an y fun ction list ed in a

%# f u n c t i o n pragma.

For example, the call to the c h a n g e _ c o l o r ma p fun ction in the sa mple

application, my _ t e s t , illustra tes t his problem. To mak e sure t he Compiler

processes t he c h a n g e _ c o l o r ma p M-file, list th e function na me in th e

%# f u n c t i o n pragma.



%# f u n c t i o n c h a n g e _ c o l o r ma p

p e a k s ;


s t y l e , p u s h b u t t o n , . . .

P o s i t i o n , [ 1 0 1 0 1 3 3 2 5 ] , . . .

S t r i n g , Ma k e Bl a c k & Wh i t e , . . .

C a l l Ba c k , c h a n g e _ c o l o r ma p ) ;

Note Inst ead of using th e %# f u n c t i o n pra gma, you can specify th e na me ofth e missin g M-file on t he Compiler comm an d line. For m ore informa tion about

this m echan isms, see the MAT LA B Com piler Users Guide.

Finding Missing Functions in an M-File

To find functions t ha t m ay n eed to be listed in a %# f u n c t i o n pra gma, check th e

text st rings specified as callback str ings or a s ar gument s to f e v a l , ODE

solvers, f mi n , f mi n s , f u n m, and f z e r o s .

To find text str ings used a s callback str ings, search for t he char acters

Callba ck or fcn in your M-file. This will find a ll th e Ca l l b a c k properties

defined by Ha ndle Gra phics objects, su ch as u icontrol and uimenu . In

Introduction

8/8/2019 sgl_lib

47/57

3-9

addition, this will find t he pr opert ies of figures a nd a xes tha t en d in F c n , such

as Cl o s e R e q u e s t F c n , tha t a lso support callbacks.

Depending on Graphics Settings in Start-Up FilesWhen you st ar t MATLAB, it execut es s t a r t u p . m, if it exist s. Your a pplication

may depend on H andle Graphics defaults t hat are set within a s t a r t u p . m file.

Workaround

If your applicat ion depend s on graph ics sett ings in a s t a r t u p . m file, includ e th es t a r t u p . m, or t he port ion of it your a pplicat ion depen ds on, in t he group of

M-files th at you compile with th e MATLAB Compiler.

Print Option Does Not Appear on File MenuIf you creat e a st an d-alone applicat ion a nd t he Prin t option does not app ear on

the File menu , it m ay indicat e tha t t he menu bar a nd t oolbar figure files in

your ap plicat ions \ b i n directory (/ b i n on UNIX systems) are n ot correct. The

first time you creat e a gra phics applicat ion, th e Compiler creat es th is directory

an d populates it with two figure files, F i g u r e Me n u Ba r . f i g and

F i g u r e T o o l Ba r . f i g . After th at , whenever you creat e graph ics a pplicat ions,

th e Compiler checks for th e existence of th ese files an d, if th ey exist, it does not

repla ce them . Your a pplicat ions b i n directory ma y conta in figure files from a

previous release of th e gra phics librar y.

Workaround

Replace th e men u bar an d t oolbar figure files in your applicat ion b i n directory

with th e versions of th ese figure files in t he MATLAB inst allat ion dir ectory

(< ma t l a b > \ e x t e r n \ i n c l u d e on PCs or < ma t l a b > / e x t e r n / i n c l u d e on UN IX

systems). When you r estar t your st an d-alone gra phics ap plicat ion, it will use

th e new figur e files.

Another way t o replace your existing figur e files with n ew figure files is to

delete your application b i n directory an d ru n t he Compiler. If th is directory

does n ot exist, th e Compiler creates it an d populates it with copies of th e figurefiles stored in t he MATLAB inst allat ion dir ectory. Ther e is no need t o

recompile your gra ph ics M-file application, especially if th is is a

tim e-cons um ing ta sk. Compiling a tr ivial M-file graph ics app licat ion is enough

to cau se th e crea tion of a n ew application b i n directory.

3 Troubleshooting

8/8/2019 sgl_lib

48/57

3-10

4

8/8/2019 sgl_lib

49/57

Reference

MATLAB C/C++ Graph ics Library . . . . . . . . . . 4-2

MATLAB 5.3 Built-In Gra phics Fu nctions . . . . . . . . 4-2

MATLAB 5.3 M-File Gra phics Fu nctions . . . . . . . . . 4-3

4 Reference

8/8/2019 sgl_lib

50/57

4-2

M ATLAB C/ C++ Gra phics Library

The MATLAB C/C++ Graphics Library is dist ributed as a single library

composed of two groups of functions:

MATLAB 5.3 built -in gr aph ics fun ctions

MATLAB 5.3 M-file graphics functions

MATLAB 5.3 Built-In Graphics FunctionsThis t able lists t he bu ilt-in functions cont ained in t he MATLAB C/C++

Graph ics Librar y. The sta nd-alone versions behave a s t he functions do for

MATLAB 5.3 except for th e r estr ictions placed by t he MATLAB Compiler 2.0.1

an d MATLAB C an d C++ Math Library 2.0.1.

Table 4 -1 : MATLAB 5 .3 Built-In Functions in the Graphics Libra ry

a x e s c o n t o u r c c o p y o b j

d e l e t e d r a g r e c t d r a wn o w

f i g u r e f i l l f i l l 3

f i n d o b j f r a me 2 i m g e t

g e t f r a me h a n d l e 2 s t r u c t i ma g e

i m2 f r a me i s h a n d l e l i g h t

l i n e l o g l o g mo v i e

p a t c h p l o t p l o t 3

r b b o x r e c t a n g l e r e s e t

r ma p p d a t a s e l e c t mo v e r e s i z e s e mi l o g x

s e mi l o g y s e t s e t a p p d a t a

s t r u c t 2 h a n d l e s u r f a c e t e x t

u i c o n t r o l u i g e t f i l e u i me n u

u i p u t f i l e u i s e t c o l o r u i s e t f o n t

wa i t f o r wa i t f o r b u t t o n p r e s s

8/8/2019 sgl_lib

51/57

4-3

M ATLAB 5 .3 M -File Gra phics Functions

This t able list s t he MATLAB M-file fun ctions conta ined in th e MATLAB C/C++Graph ics Library. The st an d-alone versions of these functions beh ave as t he

functions do in MATLAB 5.3.

Table 4 -2 : M ATLAB 5 .3 M-File Gra phics Functions in the Graphics Libra ry

a l i g n a l l c h i l d a x i s

b r i g h t e n c a mz o o m c l o s e

c l o s e r e q c l r u p r o p c o l o r d e f

c o l o r ma p c o l s t y l e d i a l o g

e r r o r d l g f i l e me n u f c n f i n d a l l

g c a g c b f g c b o

g c f g c o g e t a p p d a t a

g e t u p r o p g i n p u t h g l o a d

h g s a v e h i s t c h o l d

h s v h s v 2 r g b i s a p p d a t a

i s h o l d j e t l e g e n d

ma k e me n u me n u b a r me n u l a b e l

mo v e a x i s ms g b o x n e wp l o t

p o l a r p r i n t q u e s t d l g

r o t a t e 3 d s e t p t r s e t u p r o p

t e x t wr a p u i c l e a r mo d e u i c o n t e x t me n u

u i r e s t o r e u i r e s u me u i wa i t

v i e w wa r n d l g wa t c h o f f

wa t c h o n wh i t e b g z o o m

4 Reference

8/8/2019 sgl_lib

52/57

4-4

Index

8/8/2019 sgl_lib

53/57

I-1

Symbols%# f u n c t i o n pragma 3-8

. c s h r c 2-9

. l o g i n 2-9

/ b i n directory (UNI X)

creatin g 2-8

packaging a pplicat ions 2-14

rem oving 3-9

\ b i n directory (PCs)

creatin g 2-6packaging a pplicat ions 2-13

rem oving 3-9

AAdobe Illust ra tor

device driver 1-4

axes objects 3-7, 3-9

B- B flag

specifying bu ndle files 2-6, 2-8

building graph ics a pplicat ions 2-5

on PCs 2-5on UNIX systems 2-7

other m eth ods 2-15

bundle files

using 2-6, 2-8

C

C applicationcreatin g 2-6, 2-8

C++ applications

creatin g 2-6, 2-8

callback str ings

assigning values to works pace varia bles 3-5

finding in M-code 3-7

illegal syntax 3-4, 3-5

multi-dimensional a rra ys as ar guments 3-5

nested function calls 3-4

passin g workspa ce var iables in 3-4

scalar argum ents 3-4

sea rchin g M-files for 3-8

string argumen ts 3-5supported synt ax 3-5

tu rn ing into fun ctions 3-5

un supported coding pr actices 3-5

callbacks


color print ing

support 1-4

Compiler. S ee MATLAB Compiler 1-7

c o mp o p t s . b a t 2-15

configura tion 1-14

on PCs 1-14

on UNIX systems 1-16

Ctrl-C h andling

sta nd-alone graph ics a pplicat ions 2-12

Ddevice drivers

support 1-4

distributing graphics applications

on Microsoft Windows 2-13


drivers

support 1-4

Dynam ic Link Libra ries (DLLs)

insta lled with gra phics librar y 1-9

Index

8/8/2019 sgl_lib

54/57

I-2

required for distr ibution of gra phics applica-

tions 2-13

Eencapsulated PostScript

support 1-4

e v a l

rest rictions 1-3

unsupported featur e 3-2example a pplicat ion

f l a me s . m 1-10, 1-12

Ff e v a l 3-8

figure objects 3-7, 3-9

F i g u r e Me n u Ba r . f i g 1-10, 1-12

F i g u r e T o o l B a r . f i g 1-10, 1-12

file menu

print option 3-9

f l a me s . m 1-10, 1-12

f mi n 3-8

f mi n s 3-8

f u n m 3-8f z e r o s 3-8

GGhostscript drivers

support 1-4

global va ria bles 3-3

graph ics a pplicat ionsbuild procedure 2-5

overview 2-3

ru n-time beha vior 2-10

graphics library

configura tion 1-14

gra phics M-files

un supported coding pra ctices 1-5

g u i _ s g l . d l l 1-9

HHan dle Graphics

C a l l b a c k property 3-7, 3-8

defau lts 3-9objects 3-7, 3-8

h a r d c o p y _ s g l . d l l 1-9

har dware requirements 1-8

hea der files

l i b s g l m. h 1-10

s g l . h 1-12

Help

support in st an d-alone graph ics applicat ions

2-12

h g _ s g l . d l l 1-9

IInfo button

sta nd-alone su pport 2-12installation

files installed on PCs 1-9

files inst alled on UN IX system s 1-11


overview 1-7

procedure on PCs 1-8

verifying on PC 1-10

verifying on UN IX syst ems 1-13integer data t ypes

sup port for 1-3

unsupported feature 3-2

Index

8/8/2019 sgl_lib

55/57

I-3

Ll i b mws g l . s l 1-12

l i b mws g l . s o 1-12

libraries

linkin g 2-15

required link libra ries 2-3

library search pat h

specifying on P Cs 2-7

specifying on UNIX syst ems 2-9

l i b s g l . h 1-10license

obtaining 1-7

linking

required libra ries 2-3, 2-15

Mma th operat ions

in callback str ings 3-5

MATLAB 5.3

built-in fun ctions in gra phics libra ry 4-2

M-file graph ics functions in graph ics librar y

4-3

unsu pported featu res 3-2

MATLAB C/C++ Graphics Librarybuilt-in functions 4-2

components 1-2

MATLAB 4.2 functions 4-3

M-file functions 4-3

overview 1-2

relat ionsh ip to the MATLAB Math Librar ies

2-4

rest rictions 1-3

MATLAB C/C++ Math Library

relat ionsh ip to gra phics librar y 2-4

rest rictions 1-3

version required 1-7

MATLAB Compiler

bun dle files 2-6, 2-8

creatin g stan d-alone a pplicat ions 2-2

defined 2-3

rest rictions 1-3

run ning out side the MATLAB environment

2-9

version required 1-7

mb u i l d

configur ing t he gra phics libra ry 1-14in build pr ocedure on PCs 2-5

in build pr ocedure on UNIX systems 2-7

options files 1-14

mb u i l d options file 2-15

mb u i l d o p t s . s h 1-16

mb u i l d s g l o p t s . s h 1-16

mb u i l d

options files 2-16

mc c s a v e p a t h 2-9

menu bar gra phics file

location 1-10

M-files

creatin g stan d-alone a pplicat ions 2-2

finding callback strings 3-7

sear ching for callback st rings 3-8tr an slat ing into C or C++ code 2-3


module de finit ion file

s g l . d e f 1-10

mp a t h . d l l 1-9

multidimensional a rra ys

passed in callback str ings 3-5, 3-6

Nnested function calls 3-4

Index

O

8/8/2019 sgl_lib

56/57

I-4

Oobjects 1-3

unsupported featur e 3-2

objects (Ha ndle Gr aphics)

axes 3-7, 3-9

cont rols 3-7, 3-8

figur es 3-7, 3-9

menu s 3-7, 3-8

ODE s olvers 3-8

OpenGLrest rictions 1-3

options files

mb u i l d 1-14, 2-16

Ppainters renderer

support 1-5

p a t h

sett ing on a PC 2-7

sett ing on U NIX system s 2-9

PCs

building stan d-alone graph ics applications

2-5

packaging gra phics applications 2-13p l o t e d i t command

rest rictions 1-3

PostScript drivers

support 1-4

p r i n t command

options 1-5

support 1-3

printing

color su pport 1-4

support 1-3

troubleshooting 3-9

push buttons

un responsive 3-5

Rranges

specifying in a callback string 3-5

renderers

support 1-5

rest rictions 1-3

runtimebehavior of stand-alone applications 2-10

run -time err ors

in st an d-alone gra phics applicat ions 3-5

Sscalar a rgument s 3-4

scripts

compiling 3-3

tu rn ing into fun ctions 3-3

s g l 1-12

insta llation directory 1-9

s g l bundle file

using 2-6, 2-8

s g l . d l l 1-9

s g l . h 1-12

s g l c p p 1-12

insta llation directory 1-9

s g l c p p bundle file

using 2-6, 2-8

shar ed libraries

insta lled with gra phics librar y 1-9

required by sta nd-alone gra phics applicat ions2-13

sta nd-alone grap hics applicat ions

build procedure 2-5

building on PCs 2-5

Index

di t ib ti Mi ft Wi d 2 13 W

8/8/2019 sgl_lib

57/57

I-5

dist ribu tin g on Microsoft Windows 2-13

distr ibuting on UNIX system s 2-14

overview 2-3

ru n-time beha vior 2-10

startup options 2-9

s t a r t u p . m

compiling 3-9

string ar guments 3-5

system requirement s 1-7

Ttoolbar graphics file

location 1-10

troubleshooting

compilin g scripts 3-3

dependence on s t a r t u p . m 3-9

illegal callback syntax 3-4

missing functions 3-7

missing pr int option 3-9

un supported MATLAB featur es 3-2

Uuicontr ol objects 3-7, 3-8

uimenu objects 3-7, 3-8

u i w _ s g l . d l l 1-9

UNIX system s

building sta nd-alone gra phics applicat ions 2-7

packaging gra phics applications 2-14

unsu pported features

MATLAB 5.3 3-2

user interface elementsun responsive 3-5

Wworkspa ce var iables

assigning values in callback str ings 3-5

referenced in callback st rings 3-5

tu rn ing into global varia bles 3-3

wrapper files

generat ed by Compiler 2-6, 2-8

Zzbuffer r enderer

support 1-5

Date post:	09-Apr-2018
Category:	Documents
Upload:	kunal-bhavsar
View:	220 times
Download:	0 times

sgl_lib

Documents