14.6 Graphic commands

VEGA ZZ includes the capability to show 3D graphic objects. They can be managed by commands which syntax is very similar to OpenGL graphic language, and therefore the graphic environment is named VEGA GL (VGL).
To draw in VEGA ZZ workspace, at least one molecule must be present and the representation isn't updated automatically but it's required to call the Refresh command when new objects are added. Before to draw in the workspace, you must call VGLINIT command.

 

VGLBEGIN   (MCHAR)Primitive
Begin a new section to draw graphic primitives. The primitive vertexes must be added by VGLVERTEX command and the section must be closed by VGLEND command.

Parameters:
Primitive   

New primitive section:
  
Keyword Description
Points It treats each vertex as a single point. Vertex n defines point n. N points are drawn. The point size can be changed by VGLPOINTSIZE.
Lines It treats each pair of vertexes as an independent line segment. Vertexes 2n - 1 and 2n define line n. N/2 lines are drawn. The line width can be changed by VGLLINEWIDTH.
LineStrip It draws a connected group of line segments from the first vertex to the last. Vertexes n and n+1 define line n. N - 1 lines are drawn. The line width can be changed by VGLLINEWIDTH.
LineLoop It draws a connected group of line segments from the first vertex to the last, then back to the first. Vertexes n and n+1 define line n. The last line, however, is defined by vertexes N and 1. N lines are drawn. The line width can be changed by VGLLINEWIDTH.
Triangles It treats each triplet of vertexes as an independent triangle. Vertexes 3n - 2, 3n-1, and 3n define triangle n. N/3 triangles are drawn.
TriangleStrip Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertexes. For odd n, vertexes n, n+1, and n+2 define triangle n. For even n, vertexes n+1, n, and n+2 define triangle n. N - 2 triangles are drawn.
TriangleFan It draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertexes. Vertexes 1, n+1, and n+2 define triangle n. N - 2 triangles are drawn.
Quads It treats each group of four vertexes as an independent quadrilateral. Vertexes 4n - 3, 4n - 2, 4n - 1, and 4n define quadrilateral n. N/4 quadrilaterals are drawn.
QuadStrip Draws a connected group of quadrilaterals. One quadrilateral is defined for each pair of vertexes presented after the first pair. Vertexes 2n - 1, 2n, 2n+2, and 2n+1 define quadrilateral n. N quadrilaterals are drawn. Note that the order in which vertexes are used to construct a quadrilateral from strip data is different from that used with independent data.
Polygon Draws a single, convex polygon. Vertexes 1 through N define this polygon. Non-convex polygon can't be drawn with this function and a tessellation procedure is required.
Spheres It treats each vertex as a single sphere. Vertex n defines point n. N points are drawn. See VGLRADIUS and VGLRADIUS3 to change the sphere radius.
Cylinders It draws a connected group of cylinders from the first vertex to the last. Vertexes n and n+1 define line n. N - 1 lines are drawn. Look VGLRADIUS to change the cylinder radius. To draw a cone, one vertex must have a null cylinder radius.
CylinderStrip It draws a connected group of cylinders from the first vertex to the last. Vertexes n and n+1 define line n. N - 1 lines are drawn. In the junction of two cylinders a sphere is added. Look VGLRADIUS to change the cylinder radius.
CylinderLoop It draws a connected group of cylinders from the first vertex to the last, then back to the first. Vertexes n and n+1 define line n. The last line, however, is defined by vertexes N and 1. N lines are drawn. In the junction of two cylinders a sphere is added. Look VGLRADIUS to change the cylinder radius.

Return values:
Error code if it fails.

 

Example:
VGLBEGIN   LineLoop
VGLVERTEX   -1   -1   0
VGLVERTEX   1   -1   0
VGLVERTEX    1   1   0
VGLVERTEX    -1   1   0
VGLEND

 

See also:
VGLCOLOR, VGLCOLORRGB, VGLEND, VGLNORMAL, VGLVERTEX.

VGLCOLOR   (INT)Color
Change the current color used to draw a primitive.

Parameters:
Color  

New color in 32 bit RGBA format. Each component is 8 bit wide.:

Return values:
Error code if it fails.

 

Example:
VGLBEGIN   Triangles
VGLCOLOR   -1
VGLVERTEX   -1   -1   0
...
VGLEND

 

See also:
VGLCOLORRGB, VGLVERTEX.

VGLCOLORRGB   (INT)R   (INT)G   (INT)B
Change the current color used to draw a primitive.

Parameters:
R    

Red component (from 0 to 255).
G

Green component (from 0 to 255).
B

Blue component (from 0 to 255).

Return values:
Error code if it fails.

 

Example:
VGLBEGIN   Triangles
VGLCOLOR   255   0   0
VGLVERTEX   -1   -1   0
...
VGLEND

 

See also:
VGLCOLOR, VGLVERTEX.

VGLDISABLE   (MCHAR)Function
Disable a function used in the rendering pipeline.

Parameters:

Function

   

For the list of the functions, see VGLENABLE.

Return values:
Error code if it fails.

 

Example:
VGLDISABLE   LineStipple

 

See also:
VGLENABLE.

VGLENABLE   (MCHAR)Function
Enable a function used in the rendering pipeline.

Parameters:
Function    

Rendering function to enable:
     
  
Function Description
Blend Enable the alpha-blending.
CalcNorm

Calculate the surface normals automatically applying the flat-shading algorithm (default). For the vertex-shading algorithm, you must disable this function and you must specify the vertex normals with the VGLNORMAL commans.
CylinderDisk

Close the cylinder extremities with two disks.
LineStipple

Enable the line stipple.

Return values:
Error code if it fails.

 

Example:
VGLENABLE   CylinderDisk

 

See also:
VGLDISABLE.

VGLEND
End the primitive section.

 

Parameters:
None.

 

Return values:
Error code if it fails. If the VGLBEGIN command is not present, an error occurs.

 

Example:
VGLBEGIN   Cylinders
...
VGLEND

 

See also:
VGLBEGIN, VGLVERTEX.

VGLGROUPBEGIN
Begin a group of primitives. That's useful to manage the primitives when they are already putted in the rendering pipeline.

 

Parameters:
None.

 

Return values:
The command return the group ID that will be used to manipulate the primitives with other commands.

 

Example:
VGLGROUPBEGIN
...
VGLGROUPEND

 

See also:
VGLGROUPEND.

VGLGROUPEND
End a group of primitives. That's useful to manage the primitives when they are already putted in the rendering pipeline.

 

Parameters:
None.

 

Return values:
Error code if it fails.

 

Example:
VGLGROUPBEGIN
...
VGLGROUPEND

 

See also:
VGLGROUPBEGIN.

VGLGROUPHIDE   (UINT)GroupID
Hide a group of objects.

Parameters:
GroupID   

Group ID returned by VGLGROUPBEGIN command.

Return values:
Error code if it fails.

 

Example:
VGLGROUPHIDE   257

 

See also:
VGLGROUPBEGIN, VGLGROUPSHOW.

VGLGROUPREMOVE   (UINT)GroupID
Remove a group of objects from the display pipeline.

Parameters:
GroupID   

Group ID returned by VGLGROUPBEGIN command.

Return values:
Error code if it fails.

 

Example:
VGLGROUPREMOVE   257

 

See also:
VGLGROUPBEGIN, VGLGROUPEND.

VGLGROUSHOW   (UINT)GroupID
Show a group of objects.

Parameters:
GroupID   

Group ID returned by VGLGROUPBEGIN command.

Return values:
Error code if it fails.

 

Example:
VGLGROUPHIDE   257

 

See also:
VGLGROUPBEGIN, VGLGROUPHIDE.

VGLINIT
Initialize the rendering pipeline. It must be called always when you decide to use the VEGA GL commands.

 

Parameters:
None.

 

Return values:
Error code if it fails.

 

Example:
VGLINIT

 

See also:
None.

VGLLABEL   (FLOAT)X   (FLOAT)Y   (FLOAT)Z   (CHAR)Text
Add a new text label using the current color.

Parameters:
X    X coordinate.
Y Y coordinate.
Z Z coordinate.
Text Text string.

Return values:
The command returns the label ID.

 

Example:
VGLLABEL   1   -2   0.75 "Hello World !"

 

See also:
VGLCOLOR, VGLCOLORRGB.

VGLLINEWIDTH   (FLOAT)Width
Change the line width. The new value will be applied to the new lines generated after this command.

Parameters:
Width    Line width. The default value is 1.0.

Return values:
Error code if it fails.

 

Example:
VGLLINEWIDTH   2.5

 

See also:
VGLBEGIN, VGLEND.

VGLLOADIDENTITY
Replace the current transformation matrix with the identity matrix. The identity matrix is:

|
|
|
|
|		 1 0 0 0 |
|
|
|
|
0 1 0 0
0 0 1 0
0 0 0 1

Parameters:
None.

 

Return values:
Error code if it fails.

 

Example:
VGLLOADIDENTITY

 

See also:
VGLPOPMATRIX, VGLPUSHMATRIX.

VGLNORMAL   (FLOAT)X   (FLOAT)Y   (FLOAT)Z
Change the current normal vector used to calculate the lighting effects. The command has effect only if the CalcNorm function is disabled (see VGLDISABLE). The values must be in the -1 to 1 range.

Parameters:
X     X coordinate (default 0.0).
Y Y coordinate (default 0.0).
Z Z coordinate (default 1.0).

Return values:
Error code if it fails.

 

Example:
VGLNORMAL   1   0   -1

 

See also:
VGLBEGIN, VGLDISABLE, VGLENABLE, VGLEND, VGLVERTEX.

VGLPOINTSIZE   (FLOAT)PointSize
Change the point size. The new value will be applied to the new points added after this command.

Parameters:
PointSize    Line width. The default value is 1.0.

Return values:
Error code if it fails.

 

Example:
VGLPOINTSIZE   1.5

 

See also:
VGLBEGIN, VGLEND.

VGLPOPMATRIX
Pop the current matrix from stack.

 

Parameters:
None.

 

Return values:
Error code if it fails.

 

Example:
VGLPUSHMATRIX
...
VGLPOPMATRIX

 

See also:
VGLPUSHMATRIX.

VGLPUSHMATRIX
Push the current matrix to stack.

 

Parameters:
None.

 

Return values:
Error code if it fails.

 

Example:
VGLPUSHMATRIX
...
VGLPOPMATRIX

 

See also:
VGLPOPMATRIX.

VGLRADIUS   (FLOAT)Radius
Change the x, y, z radii at the same time. The new value will be applied to the new primitives (cylinders, spheres) added after this command.

Parameters:
Radius    Radius value. The default value is 1.0.

Return values:
Error code if it fails.

 

Example:
VGLRADIUS   3.5

 

See also:
VGLBEGIN, VGLEND, VGLRADIUS3.

VGLRADIUS3  (FLOAT)XRadius   (FLOAT)YRadius   (FLOAT)ZRadius
Change the x, y, z radii. The new values will be applied to the new primitives (spheres) generated after this command.

Parameters:
XRadius   

X-radius value. The default value is 1.0.
YRadius

Y-radius value. The default value is 1.0.
ZRadius

Z-radius value. The default value is 1.0.

Return values:
Error code if it fails.

 

Example:
VGLRADIUS3   1   2   1

 

See also:
VGLBEGIN, VGLEND, VGLRADIUS.

VGLROTATE  (FLOAT)Angle   (FLOAT)X   (FLOAT)Y   (FLOAT)Z
Add a new vertex to the primitive using the current parameters (color, normal, radius, etc). It must be placed inside the VGLBEGIN ... VGLEND section, otherwise an error message is shown.

Parameters:
Angle    Rotation angle in degree.
X     Vector X coordinate.
Y    Vector Y coordinate.
Z    Vector Z coordinate.

Return values:
Error code if it fails.

 

Example:
VGLVERTEX   90   1   0   0

 

See also:
VGLSCALE, VGLTRANSLATE.

VGLTRANSLATE  (FLOAT)X   (FLOAT)Y   (FLOAT)Z
Multiply the current matrix by translation matrix.

Parameters:
X     X translation.
Y    Y translation.
Z    Z translation.

Return values:
Error code if it fails.

 

Example:
VGLTRANSLATE   1   -5   8

 

See also:
VGLSCALE, VGLROTATE.

VGLSCALE   (FLOAT)X   (FLOAT)Y   (FLOAT)Z
Multiply the current matrix by general scaling matrix.

Parameters:
X     X scale factor.
Y    Y scale factor.
Z    Z scale factor.

Return values:
Error code if it fails.

 

Example:
VGLPUSHMATRIX
VGLSCALE   2   2   2
...
VGLPOPMATRIX

See also:
VGLROTATE, VGLTRANSLATE.

VGLVERTEX   (FLOAT)X   (FLOAT)Y   (FLOAT)Z
Add a new vertex to the primitive using the current parameters (color, normal, radius, etc). It must be placed inside the VGLBEGIN ... VGLEND section, otherwise an error message is shown.

Parameters:
X     X coordinate.
Y Y coordinate.
Z Z coordinate.

Return values:
Error code if it fails.

 

Example:
VGLBEGIN   Points
VGLVERTEX   1   1.5   -2.0
...
VGLEND

 

See also:
VGLBEGIN, VGLCOLOR, VGLCOLORRGB, VGLEND, VGLNORMAL, VGLRADIUS, VGLRADIUS3.

Back to the command index