/* simplefb
*
* provide simple image blitting and stuff for framebuffers
*
* Gunnar Zötl <gz@tset.de>, 2014
* Licensed under the terms of the MIT license. See file LICENSE for details.
*/
Usage:
------
C: #include "simplefh.h", link with simplefb
Lua: sfb = require "simplefb"
Utilities
---------
C: const char* fb_geterrstr();
Returns a string describing the last error that occurred. Returns
NULL if no description is available.
Lua: error strings are returned as second return value from the
functions that produce them, if the first return value is nil.
Framebuffer
-----------
C: fb_framebuf* fb_open(const char* fb_name)
Lua: fb = sfb.fb_open(name)
open a framebuffer device.
C: Returns 0 on failure, a pointer to a fb_framebuf on success.
Lua: Returns nil+error on failure, a fb_framebuf object on success.
C: void fb_clear(fb_framebuf *fb, uint32_t col)
Lua: sfb.fb_clear(fb, col)
clears a framebuffer to a color. The color must be in framebuffer
color format, see fb_cvtcolor()
C: int fb_close(fb_framebuf *fb);
Lua: -
close a framebuffer device and free() associated data. Returns 1
on success, 0 on failure. See source for additional details.
Lua: This happens automatically when fb object is garbage collected.
C: #define fb_framebuffer_width(fb) ((fb)->var.xres)
Lua: w = fb.width
return framebuffer width, in pixels
C: #define fb_framebuffer_height(fb) ((fb)->var.yres)
Lua: h = fb.height
return framebuffer height, in pixels
C: void fb_setpixel(fb_framebuf *fb, uint32_t x, uint32_t y, uint32_t col)
Lua: sfb.fb_setpixel(fb, c, y, col)
sets a pixel in a framebuffer to a color. The color must be in
framebuffer color format, see fb_cvtcolor()
C: uint32_t fb_cvtcolor(fb_framebuf* fb, uint32_t col, uint32_t ch)
Lua: col = sfb.fb_cvtcolor(fb, col, ch)
converts a color from image format with ch channels to framebuffer
format.
C: int fb_blit(fb_image *img, fb_framebuf *fb, int xofs, int yofs);
Lua: ok = sfb.fb_blit(img, fb, xofs, yofs)
blit an image to a framebuffer at position xofs, yofs.
C: Returns 1 on success, 0 if the image was not blit.
Lua: dito, true or false.
Images
------
Images can have 1 to 4 bytes per pixel:
Bytes Data
1 alpha or grey
2 grey, alpha
3 red, green, blue
4 red, green, blue, alpha
C: fb_image *fb_img_new(uint32_t w, uint32_t h, uint32_t ch);
Lua: img = sfb.img_new(w, h, ch = 4)
create a new image with the given dimensions and ch channels per
pixel. ch must be from 1 to 4.
C: returns NULL on failure, a pointer to an fb_image on success.
Lua: returns nil on failure, an fb_image object on success. The
channels argument is optional and defaults to 4.
C: fb_image *fb_img_load(const char* name, int wantch);
Lua: img = sfb.img_load(name, wantch = 0)
loads an image from disc, forcing the resulting image to wantch
channels if wantch != 0. wantch must be 0..4.
C: returns NULL on failure, a pointer to an fb_image containing the
loaded image data on success.
Lua: returns nil+error on failure, an fb_image object containing the
loaded image data on success.
C: fb_image *fb_img_convert(fb_image *img, uint32_t ch);
Lua: img = sfb.img_convert
convert image to another pixel depth. ch must be 1..4.
C: returns NULL on failure, a pointer to an fb_image containing the
converted image data on success.
Lua: returns nil+error on failure, an fb_image object containing the
converted image data on success.
C: fb_img_free()
Lua: -
free()s an image.
Lua: this happens automatically when the fb_image object is garbage
collected.
C: #define fb_img_width(img) ((img)->w)
Lua: w = img.width
return image width, in pixels
C: #define fb_img_height(img) ((img)->h)
Lua: h = img.height
return image height in pixels
C: #define fb_img_depth(img) ((img)->ch)
Lua: d = img.depth
return image depth (no. channels) in bytes.
C: void fb_img_getrgba(uint32_t col, uint32_t ch, uint32_t *r, uint32_t *g, uint32_t *b, uint32_t *a)
Lua: r, g, b, a = sfb.img_getrgba(col, ch)
get r, g, b, a components from an image color with ch channels. If
the image has 3 channels, a will be 255, if it has 2 channels, r, g,
b will be grey and a will be alpha, it it has 1 channel, r, g, b,
will be grey and a will be 255.
C: uint32_t fb_img_mkcolor(uint32_t ch, uint32_t r, uint32_t g, uint32_t b, uint32_t a)
Lua: col = sfb.img_mkcolor(ch, r, g, b, a = 255)
makes an image color with n channels from r, g, b, a components. If
the desired format has 1 channel, grey will be (r+g+b)/3. If it has
2 channels, grey will be as before, alpha will be a. If it has 3
channels, a is ignored, if it has 4 channels, all 4 values are used.
C: uint32_t fb_img_cvtcolor(uint32_t col, uint32_t ch_in, uint32_t ch_out)
Lua: col = sfb.img_cvtcolor(col, ch_in, ch_out)
convert an image color with ch_in channels to an image color with
ch_out channels.
C: void fb_img_setpixel_at(uint8_t *p, uint32_t ch, uint32_t col)
Lua: -
sets the color of the image pixel pointed to by p to col with ch
channels
C: void fb_img_setpixel(fb_image *img, uint32_t x, uint32_t y, uint32_t col);
Lua: sfb.img_setpixel(img, x, y, col)
sets a pixel in an image to a color. The color must be in image color
format, with as many channels as the image has. See fb_img_mkcolor().
C: void fb_img_setpixel_alpha(fb_image *img, uint32_t x, uint32_t y, uint32_t col);
Lua: sfb.img_setpixel_alpha(8img, x, y, col)
sets a pixel in an image to a color alpha blended with the background.
The color must be in image color format, with as many channels as
the image has. See fb_img_mkcolor().
C: uint32_t fb_img_getpixel_at(uint8_t *p, uint32_t ch)
Lua: -
gets the color of the image pixel pointed to by p with ch channels
C:uint32_t fb_img_getpixel(fb_image *img, uint32_t x, uint32_t y);
Lua: col = sfb.img_getpixel(img, x, y)
gets the color of a pixel from an image. The returned color is in
image color format, with as many channels as the image has. See
fb_img_getrgba().
C: void fb_img_clear(fb_image *img, uint32_t col);
Lua: sfb.img_clear(img, col)
clears an image to a color. The color must be in image color format,
with as many channels as the image has. See fb_img_mkcolor().
C: int fb_img_blit(fb_image *img, fb_image *target, int xofs, int yofs)
Lua: ok = sfb.img_blit(img, target, xofs, yofs)
blits image img into image target at position xofs, yofs.
C: int fb_img_blit_alpha(fb_image *img, fb_image *target, int xofs, int yofs)
Lua: ok = sfb.img_blit_alpha(img, target, xofs, yofs)
blits image img into image target at position xofs, yofs with alpha
blending, i.e. new color is (alpha*new color) + ((1-alpha)*old color)
The old a component is not taken into account.
C: int fb_img_blit_color_alpha(uint32_t col, uint32_t ch, fb_image *mask, fb_image *target, int xofs, int yofs)
Lua: ok = sfb.img_blit_color_alpha(col, ch, mask, target, xofs, yofs)
blits an alpha mask into an image, using image color col with ch
channels as foreground color.
Text / Fonts
------------
C:fb_font *fb_txt_loadfont(const char *name);
Lua: fnt = sfb.txt_loadfont(name)
load a font.
C: Returns NULL on failure, or else a pointer to a fb_font.
Lua: returns nil+error on failure, a fb_font object on success.
C: void fb_txt_freefont(fb_font *f);
Lua: -
unloads a font ans free()s associated resources.
Lua: this happens automatically when the fb_font object is garbage
collected.
C: const char* fb_txt_getfontname(fb_font *f);
Lua: name = fnt.name
returns a fonts name.
C: fb_image *fb_txt_render_alpha(fb_font *f, int size, const char *str)
Lua: img = sfb.txt_render_alpha(fnt, size, str)
render a string to an alpha map (=1 byte-per-pixel image). Returns
the newly created image, or NULL (Lua: nil) on failure.
C: int fb_txt_render(fb_image *img, uint32_t col, fb_font *f, int size, const char *str, int16_t x, int16_t y);
Lua: ok = sfb.txt_render(img, col, fnt, size, str, x, y)
render a string at position x, y to image img, using font f in size
size and color col. col is in image color format with the same number
of channels img has.
C: returns 1 on success, 0 on failure.
Lua: dito with true and false.
C: int fb_txt_print(fb_framebuf *fb, uint32_t col, uint32_t ch, fb_font *f, int size, const char *str, int16_t x, int16_t y);
Lua: ok = sfb.txt_print(fb, col, ch, fnt, size, str, x, y)
prints a string directly to the frame buffer fb at position x, y,
using color col (image color format, ch channels), font f, size size.
C: returns 1 on success, 0 on failure.
Lua: dito with true and false.
int fb_txt_strsize(fb_font *f, int size, const char *str, int *w, int *h);
Lua: w, h = sfb.txt_strsize(fnt, size, str)
returns the dimensions of the string str rendered in font f at size
size.
C: On failure, returns 0 and w and h are unchanged, on success
returns 1 and w and h are width and height of the rendered string.
Lua: On failure, returns nil. On success, returns width and height
of the rendered string.