<Start> <Intro> <Install> <Legal> <Screen> <Buffer> <Sprite> <Input> <Misc> <Debug> <Utes> <Author>
Buffer Functions

Overview

Buffers are user created portions of system memory set aside to act as screens. They can be almost any width or height, limited only by available system memory. All graphics primitives are drawn to buffers before being copied to the screen.

Due to the peculiarities of some of the targets JLib is intended to work with, there is a rule that the width of any buffer that will be drawn to the screen must be a multiple of four. A width for these buffers that is a multiple of eight is more desirable, and this may become a hard rule depending on some planned targets.

Buffer memory is organised as a contiguous block of width x height UBYTES. Buffer information is kept in a buffer_rec structure. Pointers to structures of this type are used to pass buffers around the various library functions. Macros are provided for accessing information about a particular buffer:

B_X_SIZE(buff_ptr) X size of buffer in pixels

B_Y_SIZE(buff_ptr) Y size of buffer in pixels

B_MAX_X(buff_ptr) Maximum X co-ordinate in the buffer

B_MAX_Y(buff_ptr) Maximum Y co-ordinate in the buffer

B_SIZE(buff_ptr) UBYTES of memory used by buffer data

B_BUFF_PTR(buff_ptr) A pointer to the buffer memory

buffer_rec *buff_init(int width,int height);

buffer_rec *buff_free(buffer_rec *buff);

Buffers are created using the buff_init() function. This function allocates the memory needed to hold a buffer of the given width and height and returns a pointer to the structure suitable for the library graphics primitives. Once a buffer is no longer needed, it can be disposed of by calling buff_free(). This function returns a NULL pointer so that any future accesses of the handle are sure to be detected as invalid by the library.

Buffer Blitting

void buff_blit_buff_to(buffer_rec *dest,int dx,int dy,buffer_rec*src, int sx1,int sy1,int sx2,int sy2);

void buff_blit_buff_toNC(buffer_rec*dest,int dx,int dy,buffer_rec*src,int sx1,int sy1,int sx2,int sy2);

This function takes the rectangle outlined by the source buffer co-ordinates and copies it to position dx, dy in the destination buffer performing clipping as needed. Buffer blitting operations are usually orders of magnitude faster than video blitting operations, so liberal use should not adversely affect performance.

void buff_stencil_buff_to(buffer_rec *dst,int x,int y,buffer_rec*src, int sx1,int sy1,int sx2,int sy2);

void buff_stencil_buff_toNC(buffer_rec*dst,int x,int y,buffer_rec*src,int sx1,int sy1,int sx2,int sy2);

This function is just like a buffer to buffer blit except that any parts of the source buffer that are set to colour 0 (background) are treated as though they are transparent, i.e. they do not overwrite the destination buffer.

Buffer Primitives

void buff_clear (buffer_rec *buff);

void buff_fill (buffer_rec *buff,UBYTE colour);

These two functions both fill the buffer passed to them with a colour. Buff fill takes a colour parameter to indicate what colour to fill the buffer with, while buff clear fills the buffer with the background colour, colour 0. Note that these functions do not respect any drawn boundaries when filling. They overwrite the entire contents of the buffer passed to them.


Developers Note: A buff_flood_fill() routine and variants are planned.


void buff_draw_point(buffer_rec *buff,int x,int y,UBYTE c);

void buff_draw_pointNC(buffer_rec *buff,int x,int y,UBYTE c);

The function buff_draw_point() plots a coloured pixel at the location x, y in the given buffer. Note that visible point co-ordinates are in the range (0-B_MAX_X(buff)),(0-B_MAX_Y(buff)). Points outside of these ranges will not be displayed. Any data at the given co-ordinates will be overwritten.

UBYTE buff_get_point(buffer_rec *buff,int x,int y);

UBYTE buff_get_pointNC(buffer_rec *buff,int x,int y);

This function returns the colour of the pixel at co-ordinates x, y in the buffer passed as a parameter. If the co-ordinates given do not fall inside the buffer then a value of 0 is always returned.

void buff_draw_box(buffer_rec *buff,int x1,int y1,int x2,int y2,UBYTE c);

void buff_draw_boxNC(buffer_rec *buff,int x1,int y1,int x2,int y2,UBYTE c);

This function draws a box outline in the given colour, described by the top left and bottom right co-ordinates passed. If any co-ordinates fall outside of the buffer the box outline will be clipped to the buffer.

void buff_draw_rect(buffer_rec *buff,int x1,int y1,int x2,int y2,UBYTE c);

void buff_draw_rectNC(buffer_rec *buff,int x1,int y1,int x2,int y2,UBYTE c);

This function takes the same parameters as buff_draw_box() but draws a filled rectangle of the given colour rather than an outline.

void buff_draw_char(buffer_rec *buff,UBYTE letter,int x,int y,UBYTE c);

void buff_draw_charNC(buffer_rec *buff,UBYTE letter,int x,int y,UBYTE c);

This function draws an alphanumeric character at position x, y in colour c. The letter will be clipped if part or all of it falls outside of the buffer passed. Several macros have been defined to get information about a character to be drawn.

CHAR_WIDTH(ch) Width of a character in pixels.

CHAR_HEIGHT(ch) Height of a character in pixels.

HAS_FONT(ch) Is ch a printable character?

The size of letters changes according to the size of the screen. The characters used are designed to fit 80x25 onto the screen. This function is mainly intended for debugging and utility style code. Only one font is available and the characters can not be scaled. To get more font-like functionality, stencil or stamp letter sprite frames (see Sprite Functions).

void buff_draw_string(buffer_rec *buff,char *string,int x,int y,UBYTE c);

void buff_draw_stringNC(buffer_rec *buff,char *string,int x,int y,UBYTE c);

This function takes a text string and outputs it to the buffer using the buff_draw_char() function. Any non printing characters are ignored, and new line characters "\n" cause the string to move to the next 'line' which is taken to be CHAR_HEIGHT('A') pixels below the current Y co-ordinate. See the notes for character drawing functions concerning intended use.

void buff_draw_line(buffer_rec *buff,int x,int y,int x2,int y2,UBYTE c);

void buff_draw_lineNC(buffer_rec *buff,int x,int y,int x2,int y2,UBYTE c);

This function draws a line from the point x, y to point x2, y2 in the given colour. The line will be clipped if any part of it lies outside the destination buffer. Drawn lines are not anti-aliased but are consistent approximations (i.e. the same two points always give the same line).

void buff_draw_h_line(buffer_rec *buff,int x1,int y1,int x2,UBYTE c);

void buff_draw_h_lineNC(buffer_rec *buff,int x1,int y1,int x2,UBYTE c);

This function is an optimised line drawing routine for horizontal lines. It takes the start and end x co-ordinates of the line, and the y co-ordinate (which is the same at both ends).

void buff_draw_v_line(buffer_rec *buff,int x1,int y1,int y2,UBYTE c);

void buff_draw_v_lineNC(buffer_rec *buff,int x1,int y1,int y2,UBYTE c);

This function is an optimised line drawing routine for vertical lines. It takes the start and end y co-ordinates of the line, and the x co-ordinate (which is the same at both ends).

void buff_draw_ellipse(buffer_rec *buff,int x,int y,int a,int b,UBYTE c);

void buff_draw_ellipseNC(buffer_rec *buff,int x,int y,int a,int b,UBYTE c);

This function draws a hollow ellipse centred around the point x, y, with a vertical diameter of a, and a horizontal diameter of b.

void buff_filled_ellipse(buffer_rec *buff,int x,int y,int a,int b,UBYTE c);

void buff_filled_ellipseNC(buffer_rec *buff,int x,int y,int a,int b,UBYTE c);

This function is exactly the same as buff_draw_ellipse() except that a solid ellipse is drawn instead of a hollow outline.

void buff_draw_circle(buffer_rec *buff,int x,int y,int d,UBYTE c);

void buff_draw_circleNC(buffer_rec *buff,int x,int y,int d,UBYTE c);

This function draws a hollow circle centred around the point x, y, with a diameter of d pixels.

void buff_filled_circle(buffer_rec *buff,int x,int y,int d,UBYTE c);

void buff_filled_circleNC(buffer_rec *buff,int x,int y,int d,UBYTE c);

This function draws a filled circle centred around the point x, y, with a diameter of d pixels.

void buff_draw_triangle(buffer_rec *buff,int x1,int y1,int x2,int y2,int x3,int y3,UBYTE c);

void buff_draw_triangleNC(buffer_rec *buff,int x1,int y1,int x2,int y2,int x3,int y3,UBYTE c);

This function draws a hollow triangle from the three points given.

void buff_filled_triangle(buffer_rec *buff,int x1,int y1,int x2,int y2, int x3,int y3,UBYTE c);

void buff_filled_triangleNC(buffer_rec *buff,int x1,int y1,int x2,int y2, int x3,int y3,UBYTE c);

This function draws a filled triangle from the three points given.

void buff_convex_poly(buffer_rec *buff,int n,int *x,int *y,UBYTE c);

void buff_convex_polyNC(buffer_rec *buff,int n,int *x,int *y,UBYTE c);

This function draws a filled convex polygon of n vertices which are listed in the given arrays of x and y co-ordinates. Attempting to draw a concave polygon with this function will have unpredictable results (which may include crashing your machine).


Developers Note: A buff_concave_poly function is planned


void buff_hollow_poly(buffer_rec *buff,int n,int *x,int *y,UBYTE c);

void buff_hollow_polyNC(buffer_rec *buff,int n,int *x,int *y,UBYTE c);

This function draws the outline of a concave or convex polygon of n vertices which are listed in the given arrays of x and y co-ordinates.

void buff_scale_full_buff_to(buffer_rec *dest,int x1,int y1,int x2,int y2,buffer_rec *src);

void buff_scale_full_buff_toNC(buffer_rec *dest,int x1,int y1,int x2,int y2,buffer_rec *src);

Undocumented

void buff_scale_buff_to(buffer_rec*dest,int d1,int d2,int d3,int d4,buffer_rec *src,int x1,int y1,int x2,int y2);

void buff_scale_buff_toNC(buffer_rec *d,int dx1,int dy1,int dx2,int dy2,buffer_rec*s,int x1,int y1,int x2,int y2);

Undocumented.

Next Section: Sprite Functions

<Start> <Intro> <Install> <Legal> <Screen> <Buffer> <Sprite> <Input> <Misc> <Debug> <Utes> <Author>