Graphics in CsoundAV
by Gabriel Maldonado
http://csounds.com/maldonado
Graphics-related opcode quick reference
Introduction
CsoundAV
can handle animated three-dimensional graphics, basing on the OpenGL widespread
standard. OpenGL was chosen because it is supported by
most platforms, and by most accelerated graphic cards. Furthermore OpenGL is easier to understand and to program than
other 3D API (such as, for example Direct3D).
In order
to handle realtime rendering processes, new concepts have been added to
previous Csound versions. Firstly, a new engine, the graphic engine, has
been added.
Note
for programmers: this engine runs into its own thread, that is,
independently from sound thread. At present time, only a very primitive
type of synchronization between these two threads is provided, but in most
cases this should not be a big problem, because i-rate and k-rate signals are
accessible by both engines at the same time, so graphic animation timing is
actually under user control. A sort of trivial hand-made
semaphores have been used to avoid both threads to access critical sections of
code at the same time, this will be probably improved in the future,
possibly using operating system API. But, for now I
intend to yield maximum priority to portability. Actually,
graphics-related thread is the same thread of widget opcodes, but frames of
graphic-output window can be updated by means of a callback mechanism. The insertion of the chunks of code belonging to OpenGL opcodes in
the engine chain is done by copying all data to vector objects. This is not the most optimized way to implement the mechanism, and
it will be improved in the future. Code has been
written taking it into account portability between platforms, as much as
possible. However, some porting troubles could rise, depending on C++
template support provided by compilers.
End of note
Frame-rate Opcodes
This additional engine works
at a rate lower than k-rate. This rate is called
“frame-rate” and refers to the rate at which subsequent graphic
frames are shown in the screen. This rate is typically
in the range of 10 to 50 fps (frames per seconds) even if lower o
upper rates can also be set by the user (the upper fps limit is the
complexity of scene, computer speed and graphic card hardware acceleration).
However frame-rate must not be greater than k-rate.
A new type of variables has
been introduced to handle frame-rate. All frame-rate variables begin with
letter 't' (lowercase). So the term t-rate
is exactly the same term of frame-rate (in the same way as control-rate
is identical to k-rate and audio-rate is identical to a-rate).
Several opcodes operating at frame-rate have been
introduced, both signal generators and modifiers, as well as opcodes that
affect graphic output. Opcodes related to graphic output (and to
frame-rate) can be grouped into the following categories:
1.
Graphic engine setup opcodes
and opcodes related to the insertion positioning in the rendering chain.
2.
Opcodes that affect graphic output:
o
opcodes that call
low-level OpenGL API functions directly,
o
mid-level graphic
opcodes and opcodes that call GLU functions directly,
o
high level graphic
opcodes and opcodes that call GLUT functions directly,
3.
Signal generators operating at frame-rate
4.
Signal modifier operating at frame-rate
5.
Math operators operating at frame-rate
6.
Opcodes that affect control flow
7.
Opcodes related to video files and video capture
When audio
output is suppressed (with command line flag -+Y), t-rate signals
are compatible with normal k-rate signals (even if they begin with
different letter) but user have to understand and to keep in mind that they
are updated at different rates.
init-rate
variables, p-fields and constants are fully compatible with both
k-rate and t-rate, even when audio output is enabled and can be mixed in
expressions with t-rate (but k-rate variables cannot be mixed in expressions
with t-rate variables when audio is enabled, they only can when audio is
disabled).
A
simple example
Notice
that, when using graphics in CsoundAV, user need a hardware-accelerated
display adapter that supports OpenGL. If user doesn't
have this, the output will probably be extremely slow (and crashes could
occurr).
“HalloCube.orc” is a simple
example showing a rotating cube.
;***************
; HalloCube.orc
;***************
#include "OpenGL.h"
;*** include file, with a lot of OpenGL definitions. This file is
;*** distributed together with CsoundAV package
sr=100 ;*** no audio output is required
for this example, so audio rate is set to a low value
kr =100
ksmps=1
nchnls=1 ;*** this is really not necessary, but provided to appear more familiar
GLfps 30
GLpanel "OpenGL panel", 512, 512
GLpanel_end
FLrun
glLineWidth 4
GLinsert_i $GL_INIT
glMatrixMode ($GL_PROJECTION)
glLoadIdentity
glOrtho -2,2,-2,2,-2,2
glMatrixMode ($GL_MODELVIEW)
GLinsert_i $GL_NOT_VALID
glClear 0
GLinsert_i 1
;///////////////////////////////////////////////////
instr 1
;///////////////////////////////////////////////////
k1 phasor .1
k2 phasor .1432
glLoadIdentity
glRotate k1*360,1,0,0
glRotate k2*360,0,1,0
glutCube 1.5
GLinsert 1.5,0
endin
;*** end of orc
and
the score:
;**************
;HalloCube.sco
;**************
i1 0 3600
; *** end of score
Let’s
see what the orchestra contains. The first line of code contains an #include
“OpenGL.h” statement. “OpenGL.h”
is a file that contains a lot of macro definitions, and is included with
CsoundAV distribution. This file MUST be included each time
you intend to use OpenGL related opcodes. This is
necessary because a lot of OpenGL subroutines require a number to specify the
actual type of action they will do. In order to help
humans, there is no need to remember all the numbers, but user have only to use
corresponding mnemonic macro definitions. We see some examples of using
define statements in HelloCube.orc .
The orchestra header sets a
very low audio rate (sr=100), because, in this first
example, we don’t use audio output, but only graphics. In
this case, in order to suppress audio output, and to optimize performance, you
have to start CsoundAV with the -+Y flag set (a flag that enables
real-time without audio output).
Almost all opcodes related
to OpenGL have the following prefixes:
·
gl = OpenGL API
function call
·
glu = GLU
API function call
·
glut = GLUT
API function call
·
GL = graphic engine managers,
utility opcodes, and high-level routines related to OpenGL graphic output.
GLfps
opcode sets the number of frames per second of graphic output window, and
initialize the callback mechanism of graphic engine. You are not constrained to
use this callback mechanism, and you can update the graphic window frames
directly by calling GLredraw opcode, but in
most cases you will use GLfps because it guarantees less CPU overhead
and is more precise in timing.
GLpanel
and GLpanel_end opcodes are similar to FLpanel and FLpanel_end,
actually they create the graphic output window, but in most cases there are no
other opcodes between them, differently from FLpanel and FLpanel_end.
FLrun
starts both OpenGL and FLTK widget operations.
glLineWidth
opcode calls corresponding OpenGL API function only once, at the INIT stage
(see later), before any other OpenGL function.
GLinsert_i
and GLinsert opcodes set the end of an OpenGL instruction block and
insert all previous OpenGL functions belonging to the same block into a
determinate position of the rendering-engine chain. Their argument is a positive number that informs the rendering-engine-insertion
routine about the position where previous instruction block must be inserted. Greater numbers make the instruction block to be positioned later
than blocks corresponding to smaller numbers. So the user can control
the execution order of instruction blocks. Normally, the argument of GLinsert and GLinsert_i is a positive
number. Numbers -1 (defined in the macro definition $GL_INIT)
and 0 (or macro definition $GL_NOT_VALID) have a particular
meaning: -1 inserts previous instruction block at the INIT stage,
and 0 inserts previous instruction block at a special
“resize” stage, i.e. a stage that is called by graphics
engine only when graphic-output window is invalidated (i.e.
when it is moved or resized). See reference section of GLinsert
for more details.
glMatrixMode,
glLoadIdentity, and glOrtho opcodes call OpenGL API functions at
the INIT stage and when graphic window is invalidated (i.e. it is moved or
resized).
glClear
makes graphic engine to call corresponding OpenGL function every frame, at
position 1 of the rendering chain (because of the subsequent statement GLinsert_i
1).
We have now terminated the
description of instr 0. All OpenGL statements declared inside
instr 0 (i.e. at the header position, externally to any Csound instrument)
should remain active for all duration of current session. This is done
by GLinsert_i opcode.
All OpenGL
statements declared inside a normal Csound instrument, are active only for
corresponding instrument duration, i.e. they are inserted in the
rendering chain at the beginning of corresponding note, and are removed at the
end of the note itself. So user can activate/deactivate OpenGL scenes by
playing notes, in the same way Csound produces sounds and pauses with audio
opcodes. In this simple example we have a single note with
the duration of an hour.
Inside instr
1 we can see two normal k-rate generators (phasor opcodes) that output two
k-rate signals used to control some parameter of OpenGL opcodes (in this
case they make the cube to rotate). Notice that you should
not use k-rate variables for OpenGL opcode input arguments directly, when
CsoundAV is generating both graphics and audio (the reason will be
explained later). But in this case we don’t generate audio, only
graphics, so this limitation doesn’t apply now,
and we can use k-rate signals directly to control OpenGL-related opcodes.
glLoadIdentity,
glRotate and glutCube are OpenGL opcodes that are inserted at the
position 1.1 of the rendering chain by GLinsert opcode (i.e. they will
executed always AFTER the glClear statement).
This is enough, for now,
about this simple orchestra.
control-rate and frame-rate
Perhaps
the relationship between k-rate and t-rate (that is frame-rate) is the most
difficult thing to understand of of CsoundAV graphics programming. But
it is even one the most fundamental. You have to take it for
granted that k-rate is the basic rate for audio engine and t-rate
is the basic (and the only) rate for the graphic engine. k-rate MUST be greater than t-rate (this is
not a real limitation, because usually frame-rate is in the order of 10-50
fps). I remember that you can set k-rate with kr=krate statement
and t-rate with GLfps opcode. All OpenGL-related opcodes (i.e. all opcodes that begin with the
prefixes gl, GL, glu and glut work at t-rate.
Both k-rate and frame-rate
variables can begin with the letter ‘k’
when audio is suppressed and Csound parser doesn’t complain if user
uses a k-variable instead of a t-rate variable. Actually, it
is absolutely OK to mix k-rate and t-rate variables when the audio output of
CsoundAV is suppressed (-+Y flag) and sr is set to
a low value (for example 100, as in the previous example; I remember that to
suppress audio with real-time oriented orchestras CsoundAV must be called with
the command line flag -+Y), however k-rate requires more CPU cycles than frame
rates, because it is a higher rate. When audio is suppressed,
you will anyway be warned in the case of expressions mixing k-rate with t-rate
variables. But if you are using both audio and
graphics, you must not confuse (or mix) t-rate variables with k-rate variables.
In this case, parse errors will occurr instead of warnings (if this
restriction would not be present, graphic
animation would not be smooth, and it would proceed jerkily).
NOTE for experts: The reason of the prohibition of
mixing t-variables with k-variables when audio is enabled, is that audio
buffering mechanism stops processing when buffer is full and restores
processing when buffer is half-empty. This makes k-rate
signal flow not to have a regular timing inside audio engine. Frame-rate
timing must be very regular instead, so if you use a k-rate to smooth signal to
control motion of a graphic object, you will notice an irregular, disturbing
motion. This doesn’t happen if you suppress audio,
because in this case main thread engine timing is under the control of a system
timer, not under the control of audio buffering mechanism. So, normally,
you will use k-rate variables to directly control graphic motion only if
audio output is suppressed (but you can still use MIDI out). There
are many frame-rate opcodes that do similar or identical tasks with respect of
corresponding k-rate opcodes. These opcodes should be used when both audio and
graphics are running in parallel in the same orchestra
or in frame-rate loops (see later). Some opcodes that behave
like converters from k-rate to t-rate are also provided ( t(kvar), tabk2t
and set_t_del, see reference section). So user
could use k-rate opcodes to generate control-signals, and convert them
only at the last stage, directly at the input arguments of the graphic-output
opcodes operating at t-rate; however this will demand more CPU cycles.
Graphics-related opcode
reference
Graphic engine
setup-related
GLpanel
name [, iwidth, iheight, ix, iy, iborder]
GLpanel_end
GLfps
ifps [, iresolution]
GLinsert
iposition
GLinsert_i iposition
GLfullscreen
iflag
GLredraw ktrig (works at k-rate not
at t-rate)
GLclearwhen
trig, imask
GLwaitInitStage
GLratio
iratio, iflag
DESCRIPTION
Define several setup
parameters of animated graphics.
INTIALIZATION
name
- double-quoted string containing the title of graphics-output window
iwidth, iheigth, ix, iy - Width, height and position of graphics-output
window
iborder - border style of graphics-output window. See FLpanel
or other FLTK containers for a list of possible border styles.
ifps - frames per second
iresolution - fps timing resolution. Range is 0 to 1. Zero
is the finest resolution precision
iposition - position priority of previous instruction block in the
OpenGL engine instruction list loop
iflag - a flag that modifies the behavior of corresponding opcode. Valid
values are 0 or 1. See below.
imask - OpenGL parameter (see OpenGL API documentation of glClear() )
iratio - width/height ratio of the graphics displayed in OpenGL windows.
A ratio of 1/1 leaves the aspect intact in normal computer
screens.
FRAME-RATE PERFORMANCE
trig - trigger signal that bangs actions of
corresponding opcodes at t-rate
PERFORMACE
ktrig
- trigger signal that bangs actions of corresponding opcodes at k-rate
GLpanel creates an OpenGL output
window. It must be followed by the opcode GLpanel_end. These opcodes are
similar to FLpanel and FLpanel_end, but,
at present time cannot contain any child widget. So, no
opcode should be placed between GLpanel and GLpanel_end. However
OpenGL output window CAN be contained by another FLTK container, by which it is
considered as a normal widget. At present time ONLY ONE OpenGL window
can be created in an orchestra. If you create more than one
OpenGL windows, unpredictable results could occur.
GLfps
opcode sets the frame-rate and activates automatic frame updating. If it is not
present in an orchestra, frames can be updated by the user by means of GLredraw opcode, to achieve special effects; this is
a particular case. Normally it should be present with animated graphics. It is possible to set the timing resolution, a common value of iresolution
argument is 0.5
GLinsert
and GLinsert_i are special opcodes that indicate the end of an OpenGL
instruction block, and insert all previous OpenGL functions belonging to the
same block into a determinate position of the rendering-engine chain. Their
argument is a positive number that informs the
engine-chain-insertion routine about the position where previous instruction
block must be inserted. Greater numbers make the block to be
positioned later than blocks corresponding to smaller numbers. So the
user can control the execution order of instruction blocks. Normally, the
argument of GLinsert and GLinsert_i
is a positive number. Numbers -1 (defined in the macro
definition $GL_INIT) and 0 (or macro definition $GL_NOT_VALID)
have a particular meaning: the first inserts previous instruction block
at the INIT stage, and the second inserts previous instruction block at a
special “resizing” stage, i.e. a stage that is called by graphics
engine when graphic-output window is invalidated (i.e. when it is
moved or resized). Only opcodes operating at frame-rate are inserted in the
engine chain. All other opocdes (i.e. k-rate and a-rate opcodes) are ignored by
GLinsert and GLinsert_i, even if they
are placed in between two frame-rate opcode lines.
The difference between GLinsert and GLinsert_i is in that instructions
inserted with GLinsert are removed from rendering chain when the
instrument containing that instruction block is switched off; whereas
instructions inserted with GLinsert_i remain active for all Csound
session.
GLfullscreen
makes the OpenGL window to be enlarged to fit full screen size, when iflag
argument is set to 1. OpenGL window can be restored to previous size when GLfullscreen is called with iflag set
to zero.
GLredraw
allows to “manually” update OpenGL window time ktrig
argument is filled with a non-zero value. This opcode must not be used if GLfps is present in the orchestra. GLredraw operates at k-rate not at t-rate, so, due to
audio buffering issues, actual timing is not reliable. It is suggested to use GLredraw without audio enabled, or, if audio is
enabled, at very low rates (max 1/2 second) otherwise animation flow will
appear very irregular and choppy.
GLclearwhen
opcode is similar to low-level glClear API, the difference is that it
clears the screen only when trig argument assumes a non-zero
value.
GLwaitInitStage
blocks the execution of main Csound engine thread until init-stage of graphics
engine thread has been executed. Useful in most cases,
to avoid that some instruments containing OpenGL instructions are activated
before some required OpenGL initializations have been done or some
graphics objects have been created.
GLratio
sets the width/height ratio of the graphics displayed in OpenGL windows. An iratio value of 1/1 leaves the aspect intact in
normal computer screens. A iratio
value greater than 1 stretches the horizontal size, whereas a value smaller
than 1 shrinks it.
Low-level OpenGL
API-wrapping opcodes
In current
version of CsoundAV there is wrapping of most OpenGL v.1.1 API functions.
This is an alphabetical list of current implemented OpenGL wrapping opcodes:
glStencilFunc
glStencilOp
glClearStencil
|
·
glBindTexture
·
glBlendFunc
·
glCallList
·
glClear
·
glClearColor
·
glClipPlane
·
glColor
·
glColor3
·
glColorPointer
·
glCullFace
·
glDisable
·
glDisableClientState
·
glDrawBuffer
·
glDrawElements
·
glEdgeFlagPointer
·
glEnable
·
glEnableClientState
|
·
glEndList
·
glEvalCoord1
·
glEvalCoord2
·
glEvalMesh1
·
glEvalMesh2
·
glFrontFace
·
glFrustum
·
glHint
·
glIndexPointer
·
glLight
·
glLightModel
·
glLightModelv
·
glLightv
·
glLineWidth
·
glLoadIdentity
·
glLoadMatrix
·
glLoadMatrixv
·
glMap1
·
glMap2
|
·
glMaterial
·
glMatrixMode
·
glMultMatrix
·
glMultMatrixv
·
glNewList
·
glNormal3
·
glNormalPointer
·
glOrtho
·
glPixelMap
·
glPixelTransfer
·
glPopMatrix
·
glPushMatrix
·
glRotate
·
glScale
·
glShadeModel
·
GLshininess
- glStencilFunc
- glStencilOp
·
glTexCoord2
·
glTexCoordPointer
|
·
glTexEnvi
·
glTexGenfv
·
glTexGeni
·
glTranslate
·
glVertex3
·
glVertexPointer
|
Notice that:
·
Many opcodes have names
similar to corresponding OpenGL wrapped functions, but not identical.
·
All CsoundAV opcodes only
accept floats as arguments, whereas corresponding wrapped functions accept
doubles, integers, bytes or array pointers. In these
cases an internal conversion to the proper data types is done.
·
Sometimes array pointers are
changed to a list of arguments corresponding to all elements of the OpenGL
wrapped array, sometimes array pointers are replaced by Csound function
table numbers. In the last case, Csound table is considered
to be an array, and array elements are actually stored into table data space.
·
Number of arguments of CsoundAV opcodes can be
different from corresponding OpenGL wrapped functions, because of the
following reasons:
1.
an eventual array
pointer that is an argument of a wrapped function is extended in CsoundAV
opcode to make each element to correspond to a different opcode argument.
2.
Some wrapped function
arguments are removed because they are hidden internally, and set to a default
value.
·
Almost all symbolic constant definitions that
can be used with the wrapping opcodes are contained in the include
file OpenGL.h that is provided with CsoundAV. Even if
it is a text file, it should never be modified by the user. All constant definition names are the same of corresponding OpenGL
API, but the values are mostly different. User should
don’t be worry about this, only use the symbolic name in the proper
opcode arguments, by preceding them with a ‘$’ character (that
is the way Csound handles the references of macro definitions).
·
All the documentation provided
here describes only the difference between the wrapping opcodes and the
corresponding OpenGL wrapped function. A further documentation is
provided only in special cases. In almost all cases user has
to read also the documentation of the original OpenGL API functions.
There is a
book, called the OpenGL Blue Book (OpenGL Reference Manual: The
Official Reference Document to OpenGL, Version 1.2 or later) that
contains a reference documentation. Also, an online reference of OpenGL API is
placed at:
http://tc1.chemie.uni-bielefeld.de/doc/OpenGL/hp/Reference.html
I
also recommend the OpenGL Red Book (OpenGL Programming Guide: The
Official Guide to Learning OpenGL, Version 1.2 or later), to learn OpenGL
basics. An online version of Red Book is placed at:
http://fly.cc.fer.hr/~unreal/theredbook/
Both books are surely not
easy to understand for non-programmers (and even for programmers with no experience of 3D graphics). If user doesn't understand
these books, I suggest to start with the csd
examples provided with CsoundAV and eventually attempt to modify them with a
trial/error method. There is also an easier book about OpenGL
programming, titled “OpenGL SuperBible, second edition” but
it covers OpenGL topics only partially, and is mainly Windows oriented. However, there are a lot of OpenGL tutorials spread on the Internet.
The following links could be useful:
The Official OpenGL Site -
News, downloads, tutorials, books & links:-
http://www.opengl.org
The OpenGL Repository -
Downloads for OpenGL implementations:-
http://www.fortunecity.com/skyscraper/nuclear/274/
The EFnet
OpenGL FAQ:-
http://www.geocities.com/SiliconValley/Park/5625/opengl/
Information on the GLUT API:-
http://www.opengl.org/developers/documentation/glut.html
The Mesa 3-D graphics
library:-
http://www.mesa3d.org
SGI OpenGL Sample
Implementation (downloadable source):-
http://oss.sgi.com/projects/ogl-sample/
Some nice OpenGL tutorials
for beginners:-
http://nehe.gamedev.net/
Nate Robins OpenGL Page
(some tutorials and code)
http://www.xmission.com/~nate/opengl.html
The GLSetup project page:-
http://www.glsetup.com/
OpenGL Usenet groups:-
news:comp.graphics.api.opengl
Follows a list of the group of functions. Many OpenGL API
are missing at present time. These ones are indicated with “not
implemented yet”.
Vertex-related 1
glBegin
tmode
glEnd
glColor
tred, tgreen, tblue, talpha
glColor3 tred, tgreen, tblue
glColorMaterial
----- not implemented yet -----
glEdgeFlag* ----- not implemented yet -----
glFrontFace
imode
glIndex
----- not implemented yet -----
glLight
ilight, ipname, tparam
glLightv ilight, ipname, tparam0, tparam1, tparam2, tparam3
glLightModel ipname, tparam
glLightModelv ipname, tparam0, tparam1, tparam2, tparam3
glLoadIdentity
glLoadMatrix t0, t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12, t13,
t14, t15
glLoadMatrixv imatrixFunc
glMatrixMode tmode
glMultMatrix t0, t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12, t13,
t14, t15
glMultMatrixv imatrixFunc
glPushMatrix
glPopMatrix
DESCRIPTION
glBegin
and glEnd are the wrapping opcodes of
void glBegin(GLenum mode) and
void glEnd(void) OpenGL API functions
glColor
and glColor3 are the wrapping opcodes of
void glColor4f (GLfloat red, GLfloat green, GLfloat blue, GLfloat
alpha) and
void glColor3f (GLfloat red, GLfloat green, GLfloat blue) OpenGL
API functions
glFrontFace
is the wrapping opcode of
void glFrontFace(GLenum mode) OpenGL API function
glLight
and glLightv are the wrapping opcodes of
void glLightf(GLenum light, GLenum pname, GLfloat param) and
void glLightfv(GLenum light, GLenum pname, const GLfloat
*params) OpenGL API functions.
Note that, in glLightv opcode, original GLfloat
*params array pointer is turned into its four elements tparam0,
tparam1, tparam2, tparam3
glLightModel
and glLightModelv are the wrapping opcodes of
void glLightModelf(GLenum pname, GLfloat param) and
void glLightModelfv(GLenum pname, const GLfloat *params) OpenGL
API functions.
Note that, in glLightModelv opcode, original GLfloat
*params array pointer is turned into its four elements tparam0,
tparam1, tparam2, tparam3
glLoadIdentity,
glLoadMatrix, glLoadMatrixv, glMatrixMode, glMultMatrix, glMultMatrixv,
glPushMatrix and glPopMatrix are the wrapping opcodes of
void glLoadIdentity(void),
void glLoadMatrixf(const GLfloat *m),
void glMatrixMode(GLenum mode),
void glMultMatrixf(const GLfloat *m),
void glPushMatrix(void) and
void glPopMatrix(void) OpenGL API functions.
Note that, in glLoadMatrix and glMultMatrix opcodes, original GLfloat *m array pointer is
turned into its 16 elements t0, t1, ..., t15; and that, in glLoadMatrixv
and glMultMatrixv opcodes, original GLfloat *m
array pointer is turned into the Csound table number imatrixFunc
Vertex-related 2
glMaterial
tpname, tred, tgreen, tblue, talpha
Glshininess tparam
glNormal3
tnx, tny, tnz
glRasterPos* ----- not implemented yet
-----
glRect* ----- not implemented yet -----
glRotate
tangle, tx, ty, tz
glScale tx, ty, tz
glTranslate tx, ty, tz
glShadeModel
tmode
glTexCoord1
----- not implemented yet -----
glTexCoord2 ts, tt
glTexCoord3 ----- not implemented yet -----
glTexCoord4 ----- not implemented yet -----
glTexGeni
icoord, tparam
glTexGenfv icoord, ipname, tparam0, tparam1, tparam2, tparam3
glVertex1
----- not implemented yet -----
glVertex2 ----- not implemented yet -----
glVertex3 tx, ty, tz
glVertex4 ----- not implemented yet -----
DESCRIPTION
glMaterial
is the wrapping opcode of
void glMaterialfv (GLenum face, GLenum pname, const GLfloat *params) OpenGL
API function.
Note that original GLfloat *params
array pointer is turned into four elements tred, tgreen, tblue, talpha, and
the original argument GLenum face is set to GL_FRONT default
value.
Glshininess is the
wrapping opcode of
void glMaterialf (GLenum face, GLenum pname,
GLfloat param) OpenGL API function.
Note that original argument GLenum
face is set to GL_FRONT_AND_BACK default value, and
the original argument GLenum pname is set to GL_SHININESS
default value.
glNormal3
is the wrapping opcode of
void glNormal3f (GLfloat nx, GLfloat ny, GLfloat nz) OpenGL API
function.
glRotate, glScale and glTranslate are the wrapping opcodes
of
void glRotatef (GLfloat angle, GLfloat x, GLfloat y, GLfloat z)
void
glScalef (GLfloat x, GLfloat y, GLfloat z) and
void
glTranslatef (GLfloat x, GLfloat y, GLfloat z) OpenGL API functions.
glShadeModel is the wrapping opcode of
void glShadeModel (GLenum mode) OpenGL API function.
glTexCoord2
is the wrapping opcode of
void glTexCoord2f (GLfloat s, GLfloat t) OpenGL API function.
glTexGeni
and glTexGeni are the wrapping opcodes of
void glTexGeni (GLenum coord, GLenum pname, GLint param) and
void glTexGenfv (GLenum coord, GLenum pname, GLfloat *params)
OpenGL API functions.
Note that, in glTexGeni opcode,
original argument GLenum pname is set to
GL_TEXTURE_GEN_MODE default value, and that, in glTexGenfv opcode,
original GLfloat *params array pointer is spliced into its four elements
tparam0, tparam1, tparam2, tparam3
glVertex3 is
the wrapping opcode of
void glVertex3f (GLfloat x, GLfloat y, GLfloat z) OpenGL API
function.
Primitives
glBitmap
----- not implemented yet -----
glClipPlane
iplane, tcoeff1, tcoeff2, tcoeff3, tcoeff4
glCullFace tmode
glDepthRange
----- not implemented yet -----
glDrawPixels ----- not implemented yet -----
glFog ----- not implemented yet -----
glFrontFace
tmode
glFrustum
tleft, tright, tbottom, ttop, tznear, tzfar
glOrtho tleft, tright, tbottom, ttop, tnear, tfar
glLineStipple
----- not implemented yet -----
glLineWidth twidth
glPixelMap
imap, imapsize, ifn_values
glPixelStore*
----- not implemented yet -----
glPixelTransfer
ipname, tparam
glPixelZoom
----- not implemented yet -----
glPointSize ----- not implemented yet -----
glPolygonMode ----- not implemented yet -----
glPolygonStipple ----- not implemented yet -----
glRasterPos* ----- not implemented yet -----
glViewport ----- not implemented yet -----
glClearColor
tred, tgreen, tblue, talpha
glDrawBuffer
imode
glReadBuffer
----- not implemented yet -----
DESCRIPTION
glClipPlane
is the wrapping opcode of
void glClipPlane (GLenum plane, GLdouble *equation) OpenGL
API function.
Note that original GLdouble *equation array pointer
is turned into four elements tcoeff1, tcoeff2, tcoeff3, tcoeff4
glCullFace
and glFrontFace are the wrapping opcodes of
void glCullFace (GLenum mode) and
void glFrontFace (GLenum mode) OpenGL API functions.
glFrustum
is the wrapping opcode of
void glFrustum (GLdouble left, GLdouble right, GLdouble bottom, GLdouble
top, GLdouble zNear, GLdouble zFar) OpenGL API function.
glOrtho is the wrapping opcode of
void glOrtho (GLdouble left, GLdouble right, GLdouble bottom,
GLdouble top, GLdouble zNear, GLdouble zFar) OpenGL API function.
glLineWidth
is the wrapping opcode of
void glLineWidth (GLfloat width) OpenGL API function.
glPixelMap
is the wrapping opcode of
void glPixelMapfv (GLenum map, GLsizei mapsize, const GLfloat
*values) OpenGL API function.
Note that original GLfloat *values
array pointer is turned into the Csound table number ifn_values
glClearColor
is the wrapping opcode of
void glClearColor (GLclampf red, GLclampf green, GLclampf blue,
GLclampf alpha) OpenGL API function.
glDrawBuffer
is the wrapping opcode of
void glDrawBuffer (GLenum mode) OpenGL API function.
Fragments
glAlphaFunc
----- not implemented yet -----
glBlendFunc tsfactor, tdfactor
glDepthFunc ----- not implemented yet -----
glLogicOp ----- not implemented yet -----
glScissor ----- not implemented yet -----
glStencilFunc tfunc, tref, tmask
glStencilOp tfail, tzfail, tzpass
glClearStencil ts
DESCRIPTION
glBlendFunc
is the wrapping opcode of
void glBlendFunc (GLenum sfactor, GLenum dfactor) OpenGL API function.
glStencilFunc
is the wrapping opcode of
void glStencilFunc( GLenum func, GLint ref, GLuint mask )
glStencilOp is the wrapping opcode of
void glStencilOp( GLenum fail, GLenum zfail, GLenum zpass )
glClearStencil is the wrapping opcode of
void glClearStencil( GLint s )
Texture mapping
glBindTexture
tTexHandle
glTexCoord2 ts, tt
glTexCoord3 ----- not implemented yet -----
glTexCoord4 ----- not implemented yet -----
glTexGeni
icoord, tparam
glTexGenfv icoord, ipname, tcoeffx, tcoeffy, tcoeffz, tcoeffw
glTexEnvi
tparam
glTexEnvfv tred, tgreen, tblue, talpha
glTexImage1D
----- not implemented yet -----
glTexImage2D ----- not implemented yet -----
glTexParameter*
----- not implemented yet -----
DESCRIPTION
glBindTexture
is the wrapping opcode of
void glBindTexture (GLenum target, GLuint texture) OpenGL API
function.
Note that original argument GLenum target
is set to GL_TEXTURE_2D default value
glTexCoord2
is the wrapping opcode of
void glTexCoord2f (GLfloat s, GLfloat t) OpenGL API function.
glTexGen and glTexGenfv are the wrapping opcodes of
void glTexGeni (GLenum coord, GLenum pname, GLint param) and
void glTexGenfv (GLenum coord, GLenum pname, GLfloat *params)
OpenGL API functions.
Note that, in glTexGeni
opcode, original argument GLenum
pname is set to GL_TEXTURE_GEN_MODE default value. Furthermore,
original GLfloat *params
array pointer is turned into the four elements tcoeffx, tcoeffy, tcoeffz,
tcoeffw in glTexGenfv opcode.
glTexEnvi
and glTexEnvfv are the wrapping opcodes of
void glTexEnvi (GLenum target, GLenum pname, GLint param) and
void glTexEnvfv (GLenum target, GLenum pname, GLfloat *params) OpenGL
API functions.
Note that original argument GLenum target is set to GL_TEXTURE_ENV
default value and original argument GLenum pname is set to GL_TEXTURE_ENV_MODE
in glTexEnvi opcode, and to GL_TEXTURE_ENV_COLOR in glTexEnvfv
opcode. Furthermore, original GLfloat
*params array pointer is turned into four elements tred,
tgreen, tblue, talpha in glTexEnvfv opcode.
Evaluators
glEvalCoord1
tu
glEvalCoord2 tu, tv
glEvalMesh1
tmode, ti1, ti2
glEvalMesh2 tmode, ti1, ti2, tj1, tj2
glEvalPoint
----- not implemented yet -----
glMap1
itarget, iu1, iu2, iustride, iuorder, ifn_points
glMap2 itarget, iu1, iu2, iustride, iuorder, iv1, iv2, ivstride,
ivorder, ifn_points
glMapGrid1
tun, tu1, tu2
glMapGrid2 tun, tu1, tu2, tvn, tv1, tv2
DESCRIPTION
glEvalCoord1
and glEvalCoord2 are the wrapping opcodes of
void glEvalCoord1f (GLfloat u) and
void glEvalCoord2f (GLfloat u, GLfloat v) OpenGL API functions.
glEvalMesh1
and glEvalMesh2 are the wrapping opcodes of
void glEvalMesh1 (GLenum mode, GLint i1, GLint i2) and
void glEvalMesh2 (GLenum mode, GLint i1, GLint i2, GLint j1, GLint
j2) OpenGL API functions.
glMap1
and glMap2 are the wrapping opcodes of
void glMap1f (GLenum target, GLfloat u1, GLfloat u2, GLint stride,
GLint order, GLfloat *points) and
void
glMap2f (GLenum target, GLfloat u1, GLfloat u2, GLint ustride, GLint
uorder, GLfloat v1, GLfloat v2, GLint vstride, GLint vorder, GLfloat *points)
OpenGL API functions.
Note that original GLfloat *points
array pointer is turned into Csound table number ifn_points.
glMapGrid1
and glMapGrid2 are the wrapping opcodes of
void glMapGrid1f (GLint un, GLfloat u1, GLfloat u2) and
void glMapGrid2f (GLint un, GLfloat u1, GLfloat u2, GLint vn, GLfloat
v1, GLfloat v2) OpenGL API functions.
Selection and Feedback
glRenderMode
----- not implemented yet -----
glInitNames ----- not implemented yet -----
glLoadName ----- not implemented yet -----
glPopName ----- not implemented yet -----
glPushName ----- not implemented yet -----
glSelectBuffer ----- not implemented yet -----
gluPickMatrix ----- not implemented yet -----
glFeedbackBuffer ----- not implemented yet -----
glPassThrough ----- not implemented yet -----
Display Lists
glCallList
ilist
glCallLists ----- not implemented yet -----
glDeleteLists ----- not implemented yet -----
glEndList
glGenLists ----- not implemented yet -----
glIsLis ----- not implemented yet -----
glListBase ----- not implemented yet -----
ilist glNewList
DESCRIPTION
glCallList
is the wrapping opcode of
void glCallList (GLuint list) OpenGL API function.
glEndList
is the wrapping opcode of
void glEndList (void) OpenGL API function.
glNewList
is the wrapping opcode of
void glNewList (GLuint list, GLenum mode) OpenGL API function. The first input argument is generated internally by calling
glGenLists(1) and the OpenGL function is called by setting mode to
GL_COMPILE. It returns the list object (an integer number to be
used as list handle).
Vertex arrays
glArrayElement
tindex
glDrawArrays tmode, tfirst, tcount
glVertexPointer istride, ioffset, itable
glNormalPointer istride, ioffset, itable
glColorPointer istride, ioffset, itable
glIndexPointer istride, ioffset, itable
glTexCoordPointer istride, ioffset, itable
glEdgeFlagPointer istride, ioffset, itable
glGetPointerv
----- not implemented yet -----
glDrawElements tmode, icount, ifn
glInterleavedArrays
----- not implemented yet -----
glEnableClientState
iarray
glDisableClientState iarray
DESCRIPTION
N.B. In
many of these opcodes there is the additional argument ioffset,
that defines the first element to read in the corresponding Csound table.
glArrayElement
is the wrapping opcode of
void glArrayElement (GLint i) OpenGL API function.
glDrawArrays
is the wrapping opcode of
void glDrawArrays (GLenum mode, GLint first, GLsizei count)
OpenGL API function.
glVertexPointer
is the wrapping opcode of
void glVertexPointer (GLint size, GLenum type, GLsizei stride, GLvoid
*pointer) OpenGL API function.
Notice that original GLint size
argument is set to 3, GLenum type is set
to GL_FLOAT, and GLvoid *pointer array pointer is
turned into Csound table number itable.
glNormalPointer
is the wrapping opcode of
void glNormalPointer (GLenum type, GLsizei stride, GLvoid *pointer)
OpenGL API function.
Notice that original GLenum type
argument is set to GL_FLOAT and GLvoid *pointer
array pointer is turned into Csound table number itable
glColorPointer
is the wrapping opcode of
void glColorPointer (GLint size, GLenum type, GLsizei stride, GLvoid
*pointer) OpenGL API function.
Notice that original GLint size
argument is set to 3, GLenum type argument
is set to GL_FLOAT, and GLvoid *pointer array
pointer is turned into Csound table number itable
glIndexPointer
is the wrapping opcode of
void glIndexPointer (GLenum type, GLsizei stride, GLvoid *pointer)
OpenGL API function.
Notice that original GLenum type
argument is set to GL_FLOAT, and GLvoid *pointer
array pointer is turned into Csound table number itable
glTexCoordPointer
is the wrapping opcode of
void glTexCoordPointer (GLint size, GLenum type, GLsizei stride,
GLvoid *pointer) OpenGL API function.
Notice that original GLint size
argument is set to 2, GLenum type argument
is set to GL_FLOAT, and GLvoid *pointer array
pointer is turned into Csound table number itable
glEdgeFlagPointer
is the wrapping opcode of
void glEdgeFlagPointer (GLsizei stride, GLvoid *pointer) OpenGL
API function.
Notice that GLvoid *pointer
array pointer is turned into Csound table number itable
glDrawElements
is the wrapping opcode of
void glDrawElements (GLenum mode, GLsizei count, GLenum type, GLvoid
*indices) OpenGL API function.
Notice that original GLenum type
argument is set to GL_FLOAT, and GLvoid *indices
array pointer is turned into Csound table number ifn
glEnableClientState
and glDisableClientState are the wrapping opcodes of
void glEnableClientState (GLenum array) and
void glDisableClientState (GLenum array) OpenGL API functions.
Modes and Execution Reference
glEnable
icap
glDisable icap
glFinish
----- not implemented yet -----
glFlush ----- not implemented yet -----
glHint
itarget, imode
glIsEnabled
----- not implemented yet -----
DESCRIPTION
glEnable
and glDisable are the wrapping opcodes of
void glEnable (GLenum cap) and
void glDisable (GLenum cap) OpenGL API functions.
glHint
is the wrapping opcode of
void
glHint (GLenum target, GLenum mode) OpenGL API function.
State Information
glGet
----- not implemented yet -----
glGetBooleanv ----- not implemented yet -----
glGetClipPlane ----- not implemented yet -----
glGetDoublev ----- not implemented yet -----
glGetError ----- not implemented yet -----
glGetFloatv ----- not implemented yet -----
glGetIntegerv ----- not implemented yet -----
glIsEnabled ----- not implemented yet -----
glGetLight ----- not implemented yet -----
glGetMap ----- not implemented yet -----
glGetMaterial ----- not implemented yet -----
glGetPixelMap ----- not implemented yet -----
glGetPolygonStipple ----- not implemented yet -----
glGetString ----- not implemented yet -----
glGetTexEnv ----- not implemented yet -----
glGetTexGen ----- not implemented yet -----
glGetTexImage ----- not implemented yet -----
glGetTexLevelParameter ----- not implemented yet -----
glGetTexParameter ----- not implemented yet -----
glPopAttrib ----- not implemented yet -----
glPushAttrib ----- not implemented yet -----
Middle-level and
GLU-related Opcodes
Persepctive and Point of
View (trasforming coordinates)
gluPerspective
tfovy, tzNear, tzFar
gluLookAt
teyex, teyey, teyez, tcenterx, tcentery, tcenterz, tupx, tupy, tupz
gluOrtho2D
----- not implemented yet -----
DESCRIPTION
gluPerspective
is the wrapping opcode of
void gluPerspective (GLdouble fovy, GLdouble aspect, GLdouble zNear,
GLdouble zFar) GLU library function.
Notice that original GLdouble
aspect argument is set externally, by means GLratio opcode.
GluLookAt is the
wrapping opcode of
void gluLookAt (GLdouble eyex, GLdouble eyey,
GLdouble eyez, GLdouble centerx, GLdouble centery, GLdouble centerz, GLdouble
upx, GLdouble upy, GLdouble upz) GLU library function.
Simple Quadric Surfaces
ihandle
gluNewQuadric [iflag]
gluSphere
ihandle, tradius, tslices, tstacts
gluCylinder ihandle, tBaseRadius, tTopRadius, theight, tslices, tstacks
gluDisk ihandle, tInnerRadius, tOuterRadius, tslices, tloops;
gluQuadricDrawStyle
ihandle, tDrawStyle
gluQuadricNormals
ihandle, tnormals
gluQuadricTexture ihandle, tTextureCoords
DESCRIPTION
gluNewQuadric
is the wrapping opcode of
GLUquadric* gluNewQuadric (void) GLU library function.
Notice that gluNewQuadric opcode not only wraps gluNewQuadric( ) function,
but also
void gluQuadricOrientation (GLUquadric *quadObject, GLenum orientation) GLU library function.
If optional argument iflag is set to a nonzero
value, quadric orientation will be set to GLU_OUTSIDE, else, if this
argument is missing, orientation is set to GLU_INSIDE by default.
gluNewQuadric opcode creates a quadric object and returns an identifier
(ihandle argument, that is an integer number) that identifies
such object and can be used by further quadric opcodes. The
quadric object just created is automatically destroyed at the end of a CsoundAV
session.
gluSphere
is the wrapping opcode of
void gluSphere (GLUquadric *qobj, GLdouble radius, GLint slices,
GLint stacks) GLU library function.
Notice that original quadric object pointer GLUquadric
*qobj is replaced by ihandle identifier generated by gluNewQuadric
opcode.
gluCylinder
is the wrapping opcode of
void gluCylinder (GLUquadric *qobj, GLdouble baseRadius, GLdouble
topRadius, GLdouble height, GLint slices, GLint stacks) GLU library
function. Notice that original quadric object pointer GLUquadric
*qobj is replaced by ihandle identifier generated by gluNewQuadric
opcode.
gluDisk
is the wrapping opcode of
void gluDisk (GLUquadric *qobj, GLdouble innerRadius, GLdouble
outerRadius, GLint slices, GLint loops) GLU library function. Notice that original quadric object pointer GLUquadric *qobj is
replaced by ihandle identifier generated by gluNewQuadric opcode.
gluQuadricDrawStyle
is the wrapping opcode of
void gluQuadricDrawStyle (GLUquadric *quadObject, GLenum drawStyle)
GLU library function.
Notice that original quadric object pointer GLUquadric
*qobj is replaced by ihandle identifier generated by gluNewQuadric
opcode.
gluQuadricNormals
is the wrapping opcode of
void gluQuadricNormals (GLUquadric *quadObject, GLenum normals);
GLU library function.
Notice that original quadric object pointer GLUquadric
*qobj is replaced by ihandle identifier generated by gluNewQuadric
opcode.
gluQuadricTexture
is the wrapping opcode of
void gluQuadricTexture (GLUquadric *quadObject, GLboolean
textureCoords) GLU library function.
Notice that original quadric object pointer GLUquadric
*qobj is replaced by ihandle identifier generated by gluNewQuadric
opcode.
Polygon tessellation
gluTessBeginPolygon
gluTessEndPolygon