4.2 Graphics setup

Functions and variables in this group influences on overall graphics appearance. So all of them should be placed before any actual plotting function calls.

Method on mglGraph: void DefaultPlotParam ()

C function: void mgl_set_def_param (HMGL gr)

Restore initial values for all of parameters.

4.2.1 Transparency

There are several functions and variables for setup transparency. The general function is alpha which switch on/off the transparency for overall plot. It influence only for graphics which created after alpha call (with one exception, OpenGL). Function alphadef specify the default value of alpha-channel. Finally, function transptype set the kind of transparency. See section Transparency and lighting, for sample code and picture.

MGL command: alpha [val=on]

Method on mglGraph: void Alpha (bool enable)

C function: void mgl_set_alpha (HMGL gr, int enable)

Sets the transparency on/off and returns previous value of transparency. It is recommended to call this function before any plotting command. Default value is transparency off.

MGL command: alphadef val

Method on mglGraph: void SetAlphaDef (mreal val)

C function: void mgl_set_alpha_default (HMGL gr, mreal alpha)

Sets default value of alpha channel (transparency) for all plotting functions. Initial value is 0.5.

MGL command: transptype val

Method on mglGraph: void SetTranspType (int type)

C function: void mgl_set_transp_type (HMGL gr, int type)

Set the type of transparency. Possible values are:

• Normal transparency (‘0’) – below things is less visible than upper ones. It does not look well in OpenGL mode (mglGraphGL) for several surfaces.
• Glass-like transparency (‘1’) – below and upper things are commutable and just decrease intensity of light by RGB channel.
• Lamp-like transparency (‘2’) – below and upper things are commutable and are the source of some additional light. I recommend to set SetAlphaDef(0.3) or less for lamp-like transparency.

See section Types of transparency, for sample code and picture..

4.2.2 Lighting

There are several functions for setup lighting. The general function is light which switch on/off the lighting for overall plot. It influence only for graphics which created after light call (with one exception, OpenGL). Generally MathGL support up to 10 independent light sources. But in OpenGL mode only 8 of light sources is used due to OpenGL limitations. The position, color, brightness of each light source can be set separately. By default only one light source is active. It is source number 0 with white color, located at top of the plot.

MGL command: light [val=on]

Method on mglGraph: bool Light (bool enable)

C function: void mgl_set_light (HMGL gr, int enable)

Sets the using of light on/off for overall plot. Function returns previous value of lighting. Default value is lightning off.

MGL command: light num val

Method on mglGraph: void Light (int n, bool enable)

C function: void mgl_set_light_n (HMGL gr, int n, int enable)

Switch on/off n-th light source separately.

MGL command: light num xdir ydir zdir ['col'='w' br=0.5]

MGL command: light num xdir ydir zdir xpos ypos zpos ['col'='w' br=0.5]

Method on mglGraph: void AddLight (int n, mglPoint d, char c='w', mreal bright=0.5, mreal ap=0)

Method on mglGraph: void AddLight (int n, mglPoint r, mglPoint d, char c='w', mreal bright=0.5, mreal ap=0)

C function: void mgl_add_light (HMGL gr, int n, mreal dx, mreal dy, mreal dz)

C function: void mgl_add_light_ext (HMGL gr, int n, mreal dx, mreal dy, mreal dz, char c, mreal bright, mreal ap)

C function: void mgl_add_light_loc (HMGL gr, int n, mreal rx, mreal ry, mreal rz, mreal dx, mreal dy, mreal dz, char c, mreal bright, mreal ap)

The function adds a light source with identification n in direction d with color c and with brightness bright (which must be in range [0,1]). If position r is specified and isn’t NAN then light source is supposed to be local otherwise light source is supposed to be placed at infinity.

Method on mglGraph: void SetDifLight (bool enable)

C function: void mgl_set_light_dif (HMGL gr, int enable)

Set on/off to use diffusive light (only for local light sources).

MGL command: ambient val

Method on mglGraph: void SetAmbient (mreal bright=0.5)

C function: void mgl_set_ambbr (HMGL gr, mreal bright)

Sets the brightness of ambient light. The value should be in range [0,1].

4.2.3 Fog

MGL command: fog val [dz=0.25]

Method on mglGraph: void Fog (mreal d, mreal dz=0.25)

C function: void mgl_set_fog (HMGL gr, mreal d, mreal dz)

Function imitate a fog in the plot. Fog start from relative distance dz from view point and its density growths exponentially in depth. So that the fog influence is determined by law ~ 1-exp(-d*z). Here z is normalized to 1 depth of the plot. If value d=0 then the fog is absent. Note, that fog was applied at stage of image creation, not at stage of drawing. See section Adding fog, for sample code and picture.

4.2.4 Default sizes

These variables control the default (initial) values for most graphics parameters including sizes of markers, arrows, line width and so on. As any other settings these ones will influence only on plots created after the settings change.

MGL command: barwidth val

Method on mglGraph: void SetBarWidth ( mreal val)

C function: void mgl_set_bar_width (HMGL gr, mreal val)

Sets relative width of rectangles in bars, barh, boxplot, candle. Default value is 0.7.

MGL command: marksize val

Method on mglGraph: void SetMarkSize (mreal val)

C function: void mgl_set_mark_size (HMGL gr, mreal val)

Sets size of marks for 1D plotting. Default value is 1.

MGL command: arrowsize val

Method on mglGraph: void SetArrowSize (mreal val)

C function: void mgl_set_arrow_size (HMGL gr, mreal val)

Sets size of arrows for 1D plotting, lines and curves (see Primitives). Default value is 1.

MGL command: meshnum val

Method on mglGraph: void SetMeshNum (int val)

C function: void mgl_set_meshnum (HMGL gr, int num)

Sets approximate number of lines in mesh, fall, grid and also the number of hachures in vect, dew and the number of cells in cloud. By default (=0) it draws all lines/hachures/cells.

MGL command: facenum val

Method on mglGraph: void SetFaceNum (int val)

C function: void mgl_set_facenum (HMGL gr, int num)

Sets approximate number of visible faces. Can be used for speeding up drawing by cost of lower quality. By default (=0) it draws all of them.

MGL command: plotid 'id'

Method on mglGraph: void SetPlotId (const char *id)

C function: void mgl_set_plotid (HMGL gr, const char *id)

Sets default name id as filename for saving (in FLTK window for example).

Method on mglGraph: const char * GetPlotId ()

C function: const char * mgl_get_plotid (HMGL gr)

Gets default name id as filename for saving (in FLTK window for example).

4.2.5 Cutting

These variables and functions set the condition when the points are excluded (cutted) from the drawing. Note, that a point with NAN value(s) of coordinate or amplitude will be automatically excluded from the drawing. See section Cutting sample, for sample code and picture.

MGL command: cut val

Method on mglGraph: void SetCut (bool val)

C function: void mgl_set_cut (HMGL gr, int val)

Flag which determines how points outside bounding box are drawn. If it is true then points are excluded from plot (it is default) otherwise the points are projected to edges of bounding box.

MGL command: cut x1 y1 z1 x2 y2 z2

Method on mglGraph: void SetCutBox (mglPoint p1, mglPoint p1)

C function: void mgl_set_cut_box (HMGL gr, mreal x1, mreal y1, mreal z1, mreal x2, mreal y2, mreal z2)

Lower and upper edge of the box in which never points are drawn. If both edges are the same (the variables are equal) then the cutting box is empty.

MGL command: cut 'cond'

Method on mglGraph: void CutOff (const char *cond)

C function: void mgl_set_cutoff (HMGL gr, const char *cond)

Sets the cutting off condition by formula cond. This condition determine will point be plotted or not. If value of formula is nonzero then point is omitted, otherwise it plotted. Set argument as "" to disable cutting off condition.

4.2.6 Font settings

MGL command: font 'fnt' [val=6]

Font style for text and labels (see text). Initial style is ’fnt’=’:rC’ give Roman font with centering. Parameter val sets the size of font for tick and axis labels. Default font size of axis labels is 1.4 times large than for tick labels. For more detail, see Font styles.

MGL command: rotatetext val

Method on mglGraph: void SetRotatedText (bool val)

C function: void mgl_set_rotated_text (HMGL gr, int val)

Sets to use or not text rotation.

MGL command: loadfont ['name'='']

Method on mglGraph: void LoadFont (const char *name, const char *path="")

C function: void mgl_load_font (HMGL gr, const char *name, const char *path)

Load font typeface from path/name. Empty name will load default font.

Method on mglGraph: void SetFontDef (const char *fnt)

C function: void mgl_set_font_def (HMGL gr, const char * val)

Sets the font specification (see Text printing). Default is ‘rC’ – Roman font centering.

Method on mglGraph: void SetFontSize (mreal val)

C function: void mgl_set_font_size (HMGL gr, mreal val)

Sets the size of font for tick and axis labels. Default font size of axis labels is 1.4 times large than for tick labels.

Method on mglGraph: void SetFontSizePT (mreal cm, int dpi=72)

Set FontSize by size in pt and picture DPI (default is 16 pt for dpi=72).

Method on mglGraph: inline void SetFontSizeCM (mreal cm, int dpi=72)

Set FontSize by size in centimeters and picture DPI (default is 0.56 cm = 16 pt).

Method on mglGraph: inline void SetFontSizeIN (mreal cm, int dpi=72)

Set FontSize by size in inch and picture DPI (default is 0.22 in = 16 pt).

Method on mglGraph: void LoadFont (const char *name, const char *path="")

C function: void mgl_load_font (HMGL gr, const char *name, const char *path)

Load font typeface from path/name.

Method on mglGraph: void CopyFont (mglGraph * from)

C function: void mgl_copy_font (HMGL gr, HMGL gr_from)

Copy font data from another mglGraph object.

Method on mglGraph: void RestoreFont ()

C function: void mgl_restore_font (HMGL gr)

Restore font data to default typeface.

Функция С: void mgl_def_font (const char *name, const char *path)

Load default font typeface (for all newly created HMGL/mglGraph objects) from path/name.

4.2.7 Palette and colors

MGL command: palette 'colors'

Method on mglGraph: void SetPalette (const char *colors)

C function: void mgl_set_palette (HMGL gr, const char *colors)

Sets the palette as selected colors. Default value is "Hbgrcmyhlnqeup" that corresponds to colors: dark gray ‘H’, blue ‘b’, green ‘g’, red ‘r’, cyan ‘c’, magenta ‘m’, yellow ‘y’, gray ‘h’, blue-green ‘l’, sky-blue ‘n’, orange ‘q’, yellow-green ‘e’, blue-violet ‘u’, purple ‘p’. The palette is used mostly in 1D plots (see 1D plotting) for curves which styles are not specified. Internal color counter will be nullified by any change of palette. This includes even hidden change (for example, by box or axis functions).

Method on mglGraph: void SetDefScheme (const char *sch)

C function: void mgl_set_def_sch (HMGL gr, const char *sch)

Sets the sch as default color scheme. Default value is "BbcyrR".

C function: void mgl_set_color (char id, mreal r, mreal g, mreal b)

Sets RGB values for color with given id.

4.2.8 Error handling

Normally user should set it to zero by SetWarn(0); before plotting and check if GetWarnCode() or Message() return non zero after plotting. Only last warning will be saved. All warnings/errors produced by MathGL is not critical – the plot just will not be drawn.

Method on mglGraph: void SetWarn (int code, const char *info="")

C function: void mgl_set_warn (HMGL gr, int code, const char *info)

Set warning code. Normally you should call this function only for clearing the warning state, i.e. call SetWarn(0);. Text info will be printed as is if code<0.

Method on mglGraph: const char * Message ()

C function: const char * mgl_get_mess (HMGL gr)

Return messages about matters why some plot are not drawn. If returned string is empty then there are no messages.

Method on mglGraph: int GetWarnCode ()

C function: int mgl_get_warn_code (HMGL gr)

Return the numerical ID of warning about the not drawn plot. Possible values are:

mglWarnNone=0

Everything OK

mglWarnDim

Data dimension(s) is incompatible

mglWarnLow

Data dimension(s) is too small

mglWarnNeg

Minimal data value is negative

mglWarnFile

No file or wrong data dimensions

mglWarnMem

Not enough memory

mglWarnZero

Data values are zero

mglWarnLegA

Too many legend entries

mglWarnLeg

No legend entries

mglWarnSlc

Slice value is out of range

mglWarnCnt

Number of contours is zero or negative

mglWarnOpen

Couldn’t open file

mglWarnLId

Light: ID is out of range

mglWarnSize

Setsize: size(s) is zero or negative

mglWarnFmt

Format is not supported for that build

This document was generated by Build Daemon user on December 22, 2013 using texi2html 1.82.