|
|
Post by Admin on Dec 22, 2020 10:12:13 GMT
NitroLogo_small.png
Nitro Graphics Library
Nitro Graphics Library allows you to create 2D & 3D graphics utilizing your devices GPU power.
User Level: Intermediate to Advanced.
It is recommended to see example code in order to understand the API.
The module names:
nitro.graphics
nitro.events
nitro.matrix
graphics.showscreen - display graphics screenNitroLogo_small.png
Nitro Graphics Library
Nitro Graphics Library allows you to create 2D & 3D graphics utilizing your devices GPU power.
User Level: Intermediate to Advanced.
It is recommended to see example code in order to understand the API.
The module names:
nitro.graphics
nitro.events
nitro.matrix
graphics.showscreen - display graphics screen
showscreen ( )
graphics functions will be available after calling this function.
default coordinate system: x is from left to right and y is from bottom to top
hint: use getscreensize() to get screen size
graphics.hidescreen - hides graphics screen
hidescreen ( )
graphics.settitle – set graphics screen title
settitle( text )
in:
text : string, graphics screen title
graphics.showtitle – show/hide graphics screen title bar
showtitle( show )
in:
show : boolean
true shows title bar
false hides title bar
Note: to hide/show title bar manually swipe with three fingers up/down
graphics.clear – clear screen
clear()
clear( color )
color : screen clear color, when omitted white is used
graphics.getscreensize – returns overall screen size
width, height = getscreensize()
out:
width : number, screen width
height : number, screen height
this function like other graphics functions is available only after you call showscreen() function
graphics.getaspect – get screen aspect ratio
aspect = getaspect()
out:
aspect: number, screen aspect ratio
graphics.setdefaultvf – set default vertex format
setdefaultvf(vf)
in:
vf: string, vertex format
vertex format is a series of characters each characters is followed by a dimension digit
example: ‘p2c4’ is vertex that has two components for position: x, y and four components for color: r, g, b, a
chars:
p: position, components (x, y, z, w)
c: color, components (r, g, b, a)
t: texture coordinate (s, t)
graphics.setdefaultef – set default elements format
setdefaultef(ef)
in:
ef: number, element format. This is the number of bytes of elements number
1 : one byte 2^8 values
2 : two bytes 2^16 values
default value is 2
graphics.setdefaultcolor – set default vertex color
setdefaultcolor(color)
in:
color: color = {r, g, b, a}, default color when vertex format does not have color e.g.. ‘p2’
graphics.present – displays all previous drawings
present()
all primitive & sprite drawings will be displayed to screen
graphics.points - draws points
see primitive drawing…
graphics.lines - draws lines
see primitive drawing...
graphics.linestrip - draws line strip
see primitive drawing…
graphics.lineloop - draws closed line
see primitive drawings…
graphics.triangles - draws filled triangles
see primitive drawings…
graphics.trianglefan - draws filled triangles
see primitive drawings…
graphics.trianglestrip - draws filled triangles
see primitive drawings…
primitive drawing
drawing (immediate) vertices:
graphics.primitive{ v1, v2, v3, … }
graphics.primitive{ v = {v1, v2, v3, … }, vf = format}
graphics.primitive{ vt = some_vt}
graphics.primitive{ vb = some_vb}
graphics.primitive{ vbo = some_vbo}
drawing using vertex elements:
graphics.primitive{ v = {v1, v2, v3, … }, vf = format, e = {e1, e2, e3, …}}
graphics.primitive{ vt = some_vt, e = {e1, e2, e3, …}}
graphics.primitive{ vb = some_vb, e = {e1, e2, e3, …}}
graphics.primitive{ vbo = some_vbo, e = {e1, e2, e3, …}}
graphics.primitive{ v = {v1, v2, v3, … }, vf = format, eb = some_eb}
graphics.primitive{ vt = some_vt, eb = some_eb}
graphics.primitive{ vb = some_vb, eb = some_eb}
graphics.primitive{ vbo = some_vbo, eb = some_eb}
graphics.primitive{ v = {v1, v2, v3, … }, vf = format, ebo = some_ebo}
graphics.primitive{ vt = some_vt, ebo = some_ebo}
graphics.primitive{ vb = some_vb, ebo = some_ebo}
graphics.primitive{ vbo = some_vbo, ebo = some_ebo}
v1, v2, v3: are vertices (tables)
v: Lua table containing vertices
vt: table created using newvt() function
vb: vertex buffer created using newvb() function (RAM)
vbo: vertex buffer object created using newvbo() function (VRAM)
format: is vertex format. example ‘p3c4’ (position with three components, then
color with four components)
e1, e2, e3: are vertex element (numbers)
e: Lua table containing elements
et: table created using newet() function
eb: element buffer created using neweb() function (RAM)
ebo: element buffer object created using newebo() (VRAM)
primitive is one of: points, lines, linestrip, lineloop, triangles, trianglefan, trianglestrip
Note: for drawing triangles: triangles, trianglefan, and trianglestrip you can use ‘tex’ field (texture value created by newtex()), e.g. g.triangels{vbo = vbo1, tex = tex1}
graphics.newtex - create texture object located in GPU’s memory (VRAM)
texobj = newtex { file }
texobj = newtex { image, rect }
texobj = newtex { text, font, color }
in:
file: string, file path
in:
image: image created with newimage(). This promotes image to texture object
rect: rect = {x, y, width, height}, sub image area [optional].
in:
text: string, text.
font: font = {name, size}, text font
color: color = {r, g, b, a}, text color
out:
texobj : created texture object, image will be stored in GPU memory or VRAM (best drawing performance)
texobj size is texobj.size = {width, height}
if tex width or height is not power of two:
size is texobj.contentsize = {width, height}
max texture coordinates is:
(texobj.maxs, texobj.maxt)
make sure to release object when you are finished from it:
graphics.release(texobj)
graphics.tex - draws texture - located in GPU’s memory (VRAM)
tex { tex, pos, rotation, scale, alpha, anchor, rect}
in:
tex: tex object, created with newtex().
pos: point = {x, y}, image position.
rotation: number, rotation in radians (default = 0) [optional].
scale: number, image scale, default = 1 [optional].
alpha: number, image transparency, range [0, 1], default =1 [optional].
anchor: is point {x, y}, image anchor point, range of x and y is [0, 1], default = {.5,.5}) [optional]
rect: is {x, y, width, height}, specify sub image [optional]
graphics.newimage - creates image located in memory (RAM)
image = newimage { file }
image = newimage { image, rect }
image = newimage { text, font, color }
in:
file: string, image path
in:
image: image created with newimage()
rect: is {x, y, width, height}, specify sub image.
in:
text: string, text of image
font: font={name, size}, text font
color: color={r,g,b,a}, text color
out:
image : created image, image will be stored in memory or RAM
(see newtex() to store image on device GPU for best performance)
image size is image.size = {width, height}
make sure to release object when you are finished from it:
graphics.release(image)
graphics.image - draws image located in memory (RAM)
image { image, pos, rotation, scale, anchor, alpha, rect}
in:
image: image object, created with newimage().
pos: point = {x, y}, image position.
rotation: number, rotation in radians (default = 0) [optional].
scale: number, image scale, default = 1 [optional].
alpha: number, image transparency, range [0, 1], default =1 [optional].
anchor: is point {x, y}, image anchor point, range of x and y is [0, 1], default = {.5,.5}) [optional]
rect: is {x, y, width, height}, specify sub image [optional]
graphics.string - draws text
string { text, pos, font, color, rotation, scale, anchor, alpha }
in:
text: string, text to draw
pos: point = {x, y}, text position.
font: font = {name, size}, text font.
color: color = {r, g, b, a}, text color.
rotation: number, rotation in radians (default = 0) [optional].
scale: number, image scale, default = 1 [optional].
anchor: point = {x, y}, image anchor point, range of x and y is [0, 1], default = {.5,.5}) [optional]
alpha: number, image transparency, range [0, 1], default =1 [optional].
graphics.stringsize - measures text size
size = stringsize { text, font }
in:
text: string, text to measure
font: font = {name, size}, text font: font name and size
out:
size: size = {width, height}, text size
graphics.newvt - create Lua vertex table
create vertex table with all components having field names
vt = newvt{ v1, v2, v3, … }
vt = newvt{ v = {v1, v2, v3, … }, vf = format}
in:
v1,v2,v3 : vertices. Vertex format is read from default vf
in:
v : vertex table
vf : string, format of vertex example ‘p3c4’
out:
vt : vertex table (with named fields)
example use: vt[1].pos.y
graphics.newvb - create vertex buffer in memory (RAM)
vb = newvb{ v1, v2, v3, … }
vb = newvb{ v = {v1, v2, v3, … }, vf = format }
vb = newvb{ vt = some_vt}
in
v1,v2,v3: vertices, vertex format is default vf
in
v = table, vertex table
vf = string, vertex format. Example ‘p2c4’
in:
vt = vertex table create with newvt()
out:
vb : vertex buffer
Note: make sure to call release(vb) when you are done
Note: for best performance use vbo
graphics.newvbo - create vertex buffer object in GPU (VRAM)
vbo = newvbo{ v1, v2, v3, … }
vbo = newvbo{ v = {v1, v2, v3, … }, vf = format }
vbo = newvbo{ vt = some_vt}
vbo = newvbo{ vb = some_vb}
in
v1,v2,v3: vertices, vertex format is default vf
in
v = table, vertex table
vf = string, vertex format. Example ‘p2c4’
in:
vt = vertex table create with newvt()
in:
vb = vertex buffer created with newvb(). This promotes vb to vbo
out:
vbo : element buffer object
Note: make sure to call release() when you are done with it.
graphics.newet - create Lua element table
create element table having e and ef fields
et = newet{ e1, e2, e3, … }
et = newet{ e = {e1, e2, e3, … }, ef = format}
in:
e1,e2,e3 : numbers representing elements
in:
e : element table
ef : number, format of element = 1 or 2
out:
et : element table
graphics.neweb - create element buffer in memory
eb = neweb{ e1, e2, e3, … }
eb = neweb{ e = {e1, e2, e3, … }, ef = format }
eb = neweb{ et = some_et}
in
e1,e2,e3: numbers representing elements
in
e = table, element table
ef = number, element format: 1 or 2
in:
et = element table created with newet()
out:
eb : element buffer stored in RAM
Note: make sure to call release(eb) when you are done with it
Note: for best performance use ebo
graphics.newebo - create element buffer object in GPU (VRAM)
ebo = newebo{ e1, e2, e3, … }
ebo = newebo{ e = {e1, e2, e3, … }, ef = format }
ebo = newebo{ et = some_et}
ebo = newebo{ eb = some_eb}
in
e1,e2,e3: numbers representing elements
in
e = element table
ef = number, element format: 1 or 2
in:
et = element table created with newet()
in:
eb = element buffer object created with neweb(). This promotes eb to ebo
out:
ebo : element buffer object stored on GPU (VRAM)
Note: make sure to call release(ebo) when you are done with it
graphics.release - release allocated storage
release( s )
in:
s : allocated storage variable
graphics.enabledepthtest - enable depth test when rendering
enabledepthtest(enable)
in
enable: bool, enable depth test flag
graphics.enableblend - enable blending when rendering
enableblend(enable)
in
enable: bool, enable blend flag
graphics.setmodelview - set model view matrix for rendered vertices
setmodelview(modelview)
in
modelview: nitro.martrix, matrix for transforming vertices
graphics.setprojection - set projection matrix for rendered vertices
setprojection(projection)
in
projection: nitro.martrix, matrix for projecting vertices on screen
events.clear - clear events queue
clear()
events.doevents - dispatches events to handling functions
doevents()
calls touch and device rotation handling functions
events.touchbegan - touch began handling function
events.touchbegan = function (touches) … end
touches is an array of {id, x, y}
events.touchmoved - touch moved handling function
events.touchmoved = function (touches) … end
touches is an array of {id, x, y}
events.touchended - touch ended handling function
events.touchended = function (touches) … end
touches is an array of {id, x, y}
events.rotated - device rotated handling function
events.rotated = function (orientation) … end
orientation: string, one of ‘portrait’ or ’landscape’
matrix.new - create matrix object from array
m = matrix.new { m11, m12, m13, m14,
m21, m22, m23, m24,
m31, m32, m33, m34,
m41, m42, m43, m44 }
in:
mij is element at row i column j
out:
m: matrix Lua object
matrix.newidentity- create identity matrix object
m = matrix.newidentity()
out:
m: matrix object, identity matrix
matrix.newrotation - rotation matrix around vector
m = matrix.newrotation(radians, x, y, z)
in:
radians: number, angle of rotation
x, y, z: numbers, vector
out:
m: matrix object, rotation matrix a round given vector
matrix.newxrotation - rotation matrix around x-axis
m = matrix.newxrotation(radians)
in:
radians: number, angle of rotation in radians
out:
m: matrix object, rotation matrix a round positive x-axis
matrix.newyrotation - rotation matrix around y-axis
m = matrix.newyrotation(radians )
in:
radians: number, angle of rotation in radians
out:
m: matrix object, rotation matrix a round positive y-axis
matrix.newzrotation - rotation matrix around z-axis
m = matrix.newzrotation(radians )
in:
radians: number, angle of rotation in radians
out:
m: matrix object, the rotation matrix a round positive z-axis
matrix.newscale - scaling matrix
m = matrix.newscale(x, y, z)
in:
x: number, x scale
y: number, y scale
z: number, z scale
out:
m: matrix object, the scale transformation matrix
matrix.newtranslation - translation transformation matrix
m = matrix.newtranslation(x, y, z)
in:
x: number, x transition
y: number, y transition
z: number, z transition
out:
m: matrix object, the translation transformation matrix
matrix.newortho - create orthographic projection matrix
m = matrix.newortho{left, right, bottom, top, nearz, farz}
in:
left: number, the left coordinate of the projection volume in eye coordinates
right: number, the right coordinate of the projection volume in eye coordinates
bottom: number, the bottom coordinate of the projection volume in eye coordinates
top: number, the top coordinate of the projection volume in eye coordinates
nearz: number, the near coordinate of the projection volume in eye coordinates
farz: number, the far coordinate of the projection volume in eye coordinates
out:
m: matrix object, the orthographic projection matrix
matrix.newperspective - create perspective projection matrix
m = matrix.newperspective{fovy, aspect, nearz, farz}
in:
fovy: number, the angle of the vertical viewing area
aspect: number, the ratio between the horizontal and the vertical viewing area.
nearz: number, the near clipping distance. must be positive.
farz: number, the far clipping distance. Must be positive and greater than the near distance.
out:
m: matrix object, the perspective projection matrix
matrix.newfrustum - create frustum projection matrix
m = matrix.newfrustum{left, right, bottom, top, nearz, farz}
in:
left: number, the left clipping plane.
right: number, the right clipping plane.
bottom: number, the bottom clipping plane.
top: number, the top clipping plane.
nearz: number, the near clipping distance. must be positive.
farz: number, the far clipping distance. must be positive and greater than the near distance.
out:
m: matrix object, the frustum projection matrix
matrix.newlookat - create look at projection matrix
m = matrix.newlookat{eyex, eyey, eyez, centerx, centery, centerz, upx, upy, upz}
in:
eyex, eyey, eyez: numbers, eye position
centerx, centery, centerz: numbers, look at position
upx, upy, upz: numbers, cameras up vector
out:
m: matrix object, the look at projection matrix
matrix:invert - invert matrix
m = matrix:invert()
out:
m: nitro.matrix (matrix object), inverted matrix. equals nil if matrix is not invertible
matrix:transpose - transpose matrix
m = matrix:transpose()
out:
m: nitro.matrix (matrix object), transposed matrix.
matrix:rotate - concatenate matrix with a rotation around vector
m = matrix:rotate(radians, x, y, z)
in:
radians: numbers, angle of rotation in radians
x, y, z: numbers, vector
out:
m: nitro.matrix (matrix object), new matrix
matrix:rotatex - concatenate matrix with a rotation around the x-axis
m = matrix:rotatex(radians)
in:
radians: numbers, angle of rotation in radians
out:
m: nitro.matrix (matrix object), new matrix.
matrix:rotatey - concatenate matrix with a rotation around the y-axis
m = matrix:rotatey(radians)
in:
radians: numbers, angle of rotation in radians
out:
m: nitro.matrix (matrix object), new matrix
matrix:rotatez - concatenate matrix with rotation around the z-axis
m = matrix:rotatez(radians)
in:
radians: numbers, angle of rotation in radians
out:
m: nitro.matrix (matrix object), new matrix
matrix:scale - concatenate matrix with a scaling transform
m = matrix:scale(sx, sy, sz)
in:
sx: numbers, x scaling factor
sy: numbers, y scaling factor
sz: numbers, z scaling factor
out:
m: nitro.matrix (matrix object), new matrix.
matrix:translate - concatenate matrix with a translation transform
m = matrix:translate(tx, ty, tz)
in:
tx: numbers, x translation amount
ty: numbers, y translation amount
tz: numbers, z translation amount
out:
m: nitro.matrix (matrix object), new matrix.
matrix:mul - multiply by matrix
m = matrix:multiply(mat)
in:
mat: nitro.matrix (matrix object), right hand matrix
out:
m: nitro.matrix (matrix object), new matrix created by multiplying the two matrices together.
matrix:add - add matrix
m = matrix:add(mat)
in:
mat: nitro.matrix (matrix object), right hand matrix
out:
m: nitro.matrix (matrix object), new matrix created by performing a component-wise addition of two matrices.
matrix:sub - subtract matrix
m = matrix:sub(mat)
in:
mat: nitro.matrix (matrix object), right hand matrix
out:
m: nitro.matrix (matrix object), new matrix created by performing a component-wise subtracting of two matrices.
matrix:mulvec4 - transform vector
x2, y2, z2, w2 = matrix:mulvec4(x, y, z, w)
in:
x, y, z, w: nitro.matrix (matrix object), vector
out:
x2, y2, z2, w2: nitro.matrix (matrix object), new vector created by multiplying the matrix by the vector.
matrix:toarray - convert matrix to table
t = matrix:toarray()
out:
t: table representing matrix (indices 1-16)
|
|
