Skip to main content

Graphics

Common Variable​

common data:
__vm_width           canvas width
__vm_height          canvas height
__vm_bpp             Canvas Pixel Bits
__vm_speed_lvl       Device speed level (0-100), the higher the hardware speed, the larger the number
__vm_scr_width       physical screen width
__vm_scr_height      physical screen height
__vm_auto_gen_rom    Whether the development environment
color:
black             rgb value:000000    
dark_blue         rgb value:1d2b53        
dark_purple       rgb value:7e2553          
dark_green        rgb value:008751         
brown             rgb value:ab5236    
dark_gray         rgb value:5f574f        
light_gray        rgb value:c2c3c7         
white             rgb value:fff1e8    
red               rgb value:ff004d   
orange            rgb value:ffa300     
yellow            rgb value:ffec27     
green             rgb value:00e436    
blue              rgb value:29adff   
indigo            rgb value:83769c     
pink              rgb value:ff77a8   
peach             rgb value:ffccaa    

memory address:
__vm_GFX          sprite data address
__vm_MAP          map data address
__vm_FLAGS        sprite flag data address
__vm_MUSIC        music data address
__vm_SFX          audio address
__vm_USERDATA     user data address
__vm_CARTDATA     application storage data mapping address
__vm_VRAM         video memory address (corresponding to the canvas)
__vm_DRAWSTAT     drawing state address
__vm_HWSTAT       hardware status address

clip​

clip(X, Y, W, H, [CLIP_PREVIOUS])

Sets the clipping rectangle in pixels. All drawing operations will be clipped to a rectangle at x,y and width w,h.

clip() to reset.

When CLIP_PREVIOUS is true , clip the new clipping region with the old clipping region.

pset​

pset(X, Y, [COL])

Sets the pixel at x, y to a specific color.

If COL is not specified, the current drawing color is used.

for y=0,127 do
  for x=0,127 do
    pset(x, y, x*x//8)
  end
end

pget​

pget(X, Y)

Returns the color of the pixel at (X, Y) on the screen.

while true do
  X, Y = rnd(128), rnd(128)
  DX, DY = rnd(4)-2, rnd(4)-2
  pset(X, Y, pget(DX+X, DY+Y))
end

PGET returns 0 when X and Y are out of range.

sget​

sget(X, Y)

sset​

sset(X, Y, [COL])

Gets or sets the color (COL) of a sprite sheet pixel.

sget returns 0 when X and Y are out of range.

fget​

fget(N, [F])

fset​

fset(N, [F], VAL)

Gets or sets the value (VAL) of the flag F of sprite N.

F is the flag index 0..7.

VAL is TRUE or FALSE.

The initial state of flags 0..7 can be set in the sprite editor and thus can be used to create custom sprite properties. It is also possible to draw only a subset of map tiles by providing a mask in MAP().

When F is omitted, all flags are retrieved/set as a single bitfield.

fset(2, 1 | 2 | 8)   -- SETS BITS 0,1 AND 3
fset(2, 4, TRUE)     -- SETS BIT 4
print(fget(2))       -- 27 (1 | 2 | 8 | 16)

gb2312_to_utf8 (version>=6)​

strutf8=gb2312_to_utf8(strgb)

convert codepage from gb2312 to utf8 print/drawTxt_h only support utf8

print/drawTxt_h​

print(STR, X, Y, COL, OPT, SIZE, FONT)

print(STR, [COL])

drawTxt_h is a printing interface that depends on the host type, and the effect is different on different hosts.

print is a device-independent printing interface.

print 支持STR内部的特殊转义(drawTxt_h不支持):

{p0} should be a char [0-9a-f] or bin data

  • "\*{p0}" repeat the next character p0 times. ex: "\*4A" for print "AAAA"
  • "\#{p0}" draw text on a solid background color
  • "\-{p0}" move text cursor horizontally by 16-p0 pixels
  • "\|{p0}" move text cursor vertically by 16-p0 pixels
  • "\+{p0p1}" move text cursor horizontally + vertically by 16-p0 and 16-p1 pixels
  • "\^" special command
    • "c{p0}" clr screen use index color p0
    • "g" move text cursor to homex,homey
    • "h" set current text cursor to homex,homey
    • "j{p0p1}" set cursor pos to x+p0*fontwidth, y+p1*lineheight
    • "r{p0}" wrap line for maxwidth fontwidth*p0
    • "s{p0}" set tab width to p0
    • "x{p0} set char width to p0
    • "x{p0} set char height to p0
    • "w" set char width to double fontwidth
    • "t" set char height to double fontheight
    • "=" use strip mode to show
    • "p" use double size show
    • ":AABBCCDDEEFFGGHH" show user define 8x8 bitmap, use hex data
    • ".ABCDEFGH" show user define 8x8 bitmap, use bin data
    • "-{w/t/=/p}" colse special command
  • "\f{p0}" draw text with this foreground color index
  • "\n" new line
  • "\r" goto line home
  • "\b" move cursor back
  • "\t" move cursor to next tab pos

OPT is the print option

  • bit0: align the coordinates down

  • bit1-2: Alignment, 1 means right alignment, 2 means center alignment, 3 means no drawing (return width), note, print does not support, drawTxt_h takes effect

  • bit7: Do not wrap after printing

  • bit8-15: word spacing, 8bit int(ver>=10 can be negative)

SIZE is the font size, if it is an unsupported size, the default size will be used.

FONT is the font name, if it is not supported, it will use the default.

Print supported fonts: English 8(8x8), 16(8x16), default 4(4x6), Chinese 16(16x16).

Fonts supported by drawTxt_h:

ver<10: Colo-PLAY 8,12,20,32,16 (unsc,cjk,phb)，缺省12。

ver>=10: Colo-PLAY any (ascii,mascii,wascii,DIN_NATURE_Bold,gp,dig,vampire)

NatureMiniPro any(default, ascii, mascii, wascii, DIN_NATURE_Bold, gp, dig, vampire).

font_add (ver>=10)​

font_add(name,size,ttfdata,cache,rbname)

Load custom truetype font.

name fontname

size font size , for truetype font ,this should be 0.

ttfdata ttf data

cache cache size. nil or invald size will be default.

rbname rollback font name when can't find char data.

return fontobj notice, you should keep it to avoid gc

font data should be string obj, for rom size limit, you need cut ttf file, only include font data needed.

example:

  • symb.txt include all char need used.
  • call sfnttool.jar to generate new ttf file. it only include char on symb.txt

java -jar sfnttool.jar -c ./my_symb.txt ./SourceHanSansCN-Medium.ttf my.ttf

local dig=
#blob ./my.ttf

local font_tt=font_add("my",0,dig,nil,"mascii")

function _update()
    
end

function _draw()
    cls()
    drawTxt_h("12&`34",100,100,red,0,32,"my")
end

font_close (ver>=10)​

font_close(font)

移除自定义的字体

font font_add返回的字体对象

font_shrink (ver>=10)​

font_shrink(global)

清理字体缓存(节约内存)

global true表示清理自定义和全局字体缓存, false表示只清理自定义字体缓存

注意, 使用大字体渲染后,最好调用font_shrink,释放字体缓存,避免过多占用内存

cursor​

cursor(X, Y, [COL])

Set the cursor position.

If COL is specified, also sets the current color.

color​

color([COL])

Sets the current color used by plotting functions.

If COL is not specified, the current color is set to light_gray(rgb=#c2c3c7).

cls​

cls([COL])

Clears the screen and resets the clipping rectangle and printing state.

COL defaults to 0 (black).

camera​

camera([X, Y])

Set -x, -y screen offset for all drawing operations.

camera() restores the default state.

arc​

arc(X, Y, R, ANGLE1, ANGLE2, [COL])

draw arc, going anticlockwise from angle1 to angle2 angle muset be [-180,180], 0 is point [R,0], 90 is [0,-R]

  • version>=4

circ​

circ(X, Y, R, [COL])

circfill​

circfill(X, Y, R, [COL])

draw a circle of radius r or a solid circle at x,y.

If r is negative, the circle is not drawn.

oval​

oval(X0, Y0, X1, Y1, [COL])

ovalfill​

ovalfill(X0, Y0, X1, Y1, [COL])

Draws an ellipse symmetrical in x and y using the given bounding rectangle.

line​

line(X0, Y0, [X1, Y1, [COL]])

Draw a line from (X0, Y0) to (X1, Y1).

If (X1, Y1) is not given, the end of the last line drawn is used.

line() with no arguments means that the next call to line(X1, Y1) will just set the end point and not draw.

cls()
line()
FOR I=0,6 DO
  line(64+COS(I/6)*20, 64+SIN(I/6)*20, 8+I)
END

lines​

lines({x0,y0,x1,y1,...}, [COL], [CLOSE]])

According to the coordinates in the table, draw a line segment.

CLOSE indicates a closed line segment (will be connected to x0, y0).

cls()
lines({0,0,15,15,43,43,},red,true)

rect​

rect(X0, Y0, X1, Y1, [COL])

rectfill​

rectfill(X0, Y0, X1, Y1, [COL])

Draws a rectangle or filled rectangle at (X0, Y0), (X1, Y1).

polygonfill​

polygonfill({x0,y0,x1,y1,...}, [COL])

According to the coordinates in the table, fill the polygon. Note that at least 3 sets of points are required in the table, and at most 64 sets of points.

trifill​

trifill(x0,y0,x1,y1,x3,y3, [COL])

triangle fill.

pal​

pal(C0, C1, [P])

pal() replaces color c0 with c1 for one of three palette remappings (p defaults to 0):

0: paint palette.

Painting a palette remaps colors as they are painted. For example, an orange flower sprite can be drawn as a red flower by setting the 9th palette value to 8:

pal(9,8)      -- paint subsequent orange (color 9) pixels as red (color 8)
spr(1,70,60)  -- any orange pixels in the sprite will be painted red

Changing the drawing palette does not affect anything already drawn to the screen.

1: show palette

The display palette remaps the entire screen when displayed at the end of a frame. For example, if you start the program and then type pal(6,14,1), you can see that all gray (colour 6) text immediately turns pink (colour 14), even though it has already been drawn. This is useful for fullscreen effects like fade in/out.

2: Secondary Palette.

Used by fillp() to draw sprites. This provides a mapping from a single 4-bit color index to two 4-bit color indices.

pal() resets all palettes to system defaults (including transparency values).

pal(P) resets a specific palette (0..2) to the system default.

pal(TBL, [P])

When the first argument to pal is a table, assign a color to each entry. For example, to remap colors 12 and 14 to red:

pal({[12]=9, [14]=8})

Or recolor the entire screen shadow to gray (including everything already drawn):

pal({1,1,5,5,5,6,7,13,6,7,7,6,13,6,7,1}, 1)

Because table indexing starts at 1, color 0 is given at the end in this case.

palt​

palt(C, [T])

Sets the transparency of the color index to T (boolean) Enables drawing transparency via spr(), sspr(), map() and tline().

palt(8, true) -- Palette number 8 will not be drawn transparently in subsequent SPRITE/TLINE draw calls

palt() reset to default: all colors except color 0 are opaque.

When C is the only parameter, it is treated as a bitfield used to set all 16 values. Example: To set colors 0 and 1 to be transparent:

palt(0xc000)

spr​

spr(N, X, Y, [W, H], [FLIP_X], [FLIP_Y])

draw sprite N (0..n) at position X,Y.

Both W (width) and H (height) are 1, the default is 1, indicating how many sprite blocks.

Color 0 is drawn transparent by default (see palt() ).

Flip horizontally when FLIP_X is true.

Flip vertically when FLIP_Y is true.

sspr​

sspr(SX, SY, SW, SH, DX, DY, [DW, DH], [FLIP_X], [FLIP_Y])

Stretches the sprite image's rectangle (sx, sy, sw, sh) to the screen's destination rectangle (sx, sy, dw, dh). In both cases, the x and y values are the coordinates (in pixels) of the upper-left corner of the rectangle, with width w, h.

Color 0 is drawn transparent by default (see palt() ).

dw, dh default to sw, sh.

Flip horizontally when FLIP_X is true.

Flip vertically when FLIP_Y is true.

tline​

tline(X0, Y0, X1, Y1, MX, MY, MDX, MDY)

Draws a textured line between two points, sampling the map for texture data.

  • MDX: The amount to add to mx after each pixel is drawn, expressed in (fractional) map tiles. Default is 1/8 (move right one map pixel).
  • MDY: The amount to add to mx after each pixel is drawn, expressed in (fractional) map tiles. Default is 0 (a horizontal line).
  • statctl(tlmw/tlmh/tlmx/tlmy) affect the u/v mapping

tspr​

tspr(X0, Y0, X1, Y1, SPRX, SPRY, SPRDX, SPRDY)

Draws a textured line between two points, sampling the sprite for texture data.

  • SPRDX: The amount to add to mx after each pixel is drawn, expressed in (fractional) map tiles. Default is 1/8 (move right one map pixel).
  • SPRDY: The amount to add to mx after each pixel is drawn, expressed in (fractional) map tiles. Default is 0 (a horizontal line).
  • statctl(tlmw/tlmh) affect the u/v mapping

fillp​

fillp(P)

The procedural fill pattern is a 4x4 2-color tile pattern that affects the following drawing functions: circ() circfill() rect() rectfill() polygonfill() trifill() oval() ovalFill() pset() line() lines().

P is a bit field that is read sequentially starting from the most significant bit. To calculate the P-value for the desired mode, add the place values together:

  .-----------------------.
  |32768|16384| 8192| 4096|
  |-----|-----|-----|-----|
  | 2048| 1024| 512 | 256 |
  |-----|-----|-----|-----|
  | 128 |  64 |  32 |  16 |
  |-----|-----|-----|-----|
  |  8  |  4  |  2  |  1  |
  '-----------------------'

For example, fillp(4+8+64+128+ 256+512+4096+8192) will create a checkerboard pattern.

The default fill pattern is 0, which means a single solid color is drawn.

To specify a second color for the pattern, use the high bits of any color argument:

fillp(0b0011010101101000)
circfill(64,64,20, 0x4E) -- brown and pink

Other settings are given in bit 0b0.111:

0b0.100 Transparency.

When this bit is set, the second color is not drawn.

-- board with transparent squares
fillp(0b0011001111001100.1)

0b0.010 applied to sprites.

When set, the fill pattern will be applied to the sprite (spr, sspr, map, tline) using the colormap provided by the auxiliary palette.

Each pixel value in the sprite (after applying the drawing palette as usual) is treated as an index into a secondary palette. Each entry in the secondary palette contains two colors used to render the fill pattern. For example, to draw a white and red (7 and 8) checkerboard pattern for blue pixels (color 12) in a sprite:

for I=0,15 do pal(I, I+I*16, 2) end  -- all other colors map to themselves
pal(12, 0x87, 2)                     -- remap color 12 in secondary palette
 
fillp(0b0011001111001100.01)         -- checkerboard palette, applied to sprites
spr(1, 64,64)                        -- draw sprites

0b0.001 Apply secondary palette globally.

When set, secondary palette mappings are also applied to all drawing functions that respect fill patterns (circfill, line, etc.). This is useful in conjunction with sprite drawing functions, so that the color index of each sprite pixel has the same meaning as the color index provided to the drawing function.

fillp(0b0011001111001100.001)
pal(12, 0x87, 2)
circfill(64,64,20,12)                -- Red and white checkerboard circle

Auxiliary palette mappings are applied after the normal draw palette mappings. So the following will also draw a red and white square circle:

pal(3,12)
circfill(64,64,20,3)

blit​

blit(x,y,opflag,data,linebytes,w,h,bpp,flag,sx,sy,sw,sh)

draw image data block.

x, y coordinates of the upper left corner drawn.

opflag Drawing strategy

  • bit0 1 means alpha blending drawing (only 32-bit color mode is valid)
  • bit1-2 indicates the anchor point in the x direction 0: left, 1: right, 2: middle
  • bit3-4 indicates the anchor point in the y direction 0: up, 1: down, 2: middle

data Image data

data can be special data, at this time linebytes, w, h, bpp can be ignored:

  • "SPR" means use sfx image directly
  • "SCR" means use the screen directly

linebytes Data length of each line

w,h,bpp Image width, height and bits per pixel.

flag image data attribute

  • bit0 premul data (32-bit color, premultiplied alpha)
  • bit1 swap_br (need to exchange blue/red data)
  • bit2 OPAQUE (opaque, disable alpha)

sx,sy,sw,sh select the image rectangle to draw.

rotspr​

rotspr(SX, SY, SW, SH, DX, DY, ANGLE, ZOOMX, ZOOMY)

Similar to sspr, but supports rotation and scaling.

palrgb​

palrgb(idx,r,g,b,a)

Set the palette color and return the color value(this color value can be used as COL for other drawing functions).

white=palrgb(14,0xff,0xff,0xff)
circfill(64,64,20,white)

getcolor​

getcolor(r,g,b,a)

Returns a color value that can be used in plotting functions.

Note that for palette mode, the closest palette color is looked up.

red=getcolor(0xff,0,0)
circfill(64,64,20,red)

qrcode(ver>=11)​

qrcode(str,col,w,x,y)

draw qrcode at pos (x,y)-(x+w,y+w) if image out screen or w too small , will draw nothing.

return qrcode size(px width)

Note funciton will only draw valid point , backgrand need fill first.

r=qrcode('this is a test',white,177,35,35)

image​

img_load​

img_load(picdata,[bpp],[flag],[gifall])

Load image data (png/jpg format), if the bpp parameter is provided, it will be converted to the corresponding image format, otherwise, the system specification conversion will be installed.

support load gif(version>=6)

  • default only load first frame of gif
  • gifall=true will load all gif frames
  • all frames one by one on Y dir
  • gifall=true need many memory, so please calc the memery size

support load webp (only bpp=16 or 32)(version>=12)

return image object img.

img_close​

img_close(img)

Immediately release the img resource.

img_info​

img_info(img)

Return the w, h, bpp, flag of the image.

for gifall image , return w,h,bpp,flag,frame_h,delays

  • frame_h: frame height
  • delays: array for every frame delay(ms)

img_draw​

img_draw(img,x,y,opflag)

Paste the image to the x, y position, and the flag refers to the parameters of blit.

img_drawex​

img_drawex(img,x,y,opflag,sx,sy,sw,sh)

Paste the specific area of the image to the x, y position, and the flag refers to the parameters of blit.

img_drawrot [version>=12]​

img_drawrot(img, DX, DY, OPFLAG, [SX, SY, SW, SH, ANGLE, ZOOM])

refers to the rotspr

  • img's bpp must be same with spec bpp
  • OPFLAG : now please use 1
  • SX,SY,SW,SH must in the img's area

img_drawzoom [version>=12]​

img_drawzoom(img, DX, DY, DW, DH, [SX, SY, SW, SH, OPFLAG] )

zoom draw img

  • img's bpp must be same with spec bpp
  • OPFLAG :
    • bit0 : should be 1
    • bit8 : 1 for x flip
    • bit9 : 1 for y flip
  • SX,SY,SW,SH must in the img's area

img_drawgif​

img_drawex(img, frameidx, x,y,opflag,sx,sy,sw,sh)

Paste the gif frame to the x, y position, and the flag refers to the parameters of blit. return curframeidx, delaytimems

coloX-16
version 1
__lua__
local tempgif=
#blob 1.gif
local gif=img_load(tempgif,nil,nil,true)
local frmidx=1
local delay=0
function _draw()
    cls(dark_green)
    local _frmidx,_delay=img_drawgif(gif,frmidx,0,0)
    print(string.format("%d,%d,%d",frmidx,_frmidx,_delay),0,0,red,0,16)
    delay=delay+1000/30
    if delay>_delay then
        frmidx=_frmidx+1
        delay=delay-_delay
    end
end

img_gif_load [version>=6]​

img_gif_load(picdata,[bpp])

Load gif data, if the bpp parameter is provided, it will be converted to the corresponding image format, otherwise, the system specification conversion will be installed. gif frame will dynamic render for less memory use.

return image object img.

img_gif_file [version>=6]​

img_gif_file(filename,[bpp])

Load gif file, if the bpp parameter is provided, it will be converted to the corresponding image format, otherwise, the system specification conversion will be installed. gif frame will dynamic render for less memory use.

return image object img.

img_gif_next [version>=6]​

img_gif_next(img)

dynamic render gif frame.

return nil for not need update return 0 indicate the gif is end return 1 indicate has update frame

coloX-16
version 1
__lua__
local tempgif=
#blob 1.gif
local gif=img_gif_load(tempgif)
function _draw()
    cls(dark_green)
    img_gif_next(gif)
    img_draw(gif,0,0)
end

img_loadwebp(version>=12)​

img_loadwebp(picdata,[bpp],[flag],[opt,cropx,cropy,cropw,croph,sw,sh)

Load image data (webp format), if the bpp parameter is provided, it will be converted to the corresponding image format, otherwise, the system specification conversion will be installed. bpp must be 16 or 32

  • opt: bit0=1 use crop area, bit1=1 use scale
  • crop[x,y,w,h] crop params
  • sw,sh scale to sw,sh, only support zoom in

return img obj and full webp pic width/height : img,fullwidth,fullheight

rlottie​

rlottie_load​

rlottie_load(key,cont,w,h)

Load rlottie animation data, key is id (cont with the same id must be the same), w/h is rendering size, return animation object ani.

rlottie_close​

rlottie_close(ani)

Immediate release of ani resources.

rlottie_info​

rlottie_info(ani)

Return current frame, total number of frames, animation frame rate, image width, image height.

rlottie_draw​

rlottie_draw(ani,frameidx,x,y)

Draws a specific frame of the animation to an x,y position.

rlottie_prop​

rlottie_prop(ani,proptype,keypath,v1,v2,v3)

Set the attribute parameters on the animation path.

rlottie_mark​

rlottie_mark(ani)

Return animation section as a form {{name,frm_begin,frm_end},...}