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

Overview

These functions are designed to give you control over the appearance of the screen during your programs execution. You use mode setting functions to initialise the display before your program runs, and to restore it to its former state when the program ends. While your program runs you can change the palette (colour set) of the screen or blit (copy) buffers on to the screen. A screen may actually be a window or a part of a larger display area on some targets, but your code and the library will still behave in the same way as it would if the whole screen were being used by your program. There is no need to learn complex window manipulation API's for each target.

Buffers can be blitted to any screen co-ordinates. Negative co-ordinates or co-ordinates larger than the current screen dimensions may mean that part or all of the buffer is clipped(not shown).

Initialisation

Paging

Manipulation

Screen Palette Functions

Non-Screen Palette Functions

Blittting

Screen Initialisation

void screen_set_video_mode(void);

void screen_restore_video_mode(void);

These functions set and restore the graphics mode for your program as it runs. You must call screen_set_video_mode() once in your program before you attempt any graphical operations. This routine will perform the initialisation and set up activities particular to your target, such as opening an output window or changing the graphics resolution. You must always call screen_restore_video_mode() before your program ends to restore the graphical state of the host system. Failing to call either of these functions before and then after performing graphics operations could cause fatal crashes on some operating systems. The exact behaviour of programs in this situation is undefined.

Once the video mode is set, you may output to the screen. The characteristics of the mode JLib was built for are available to your program as a number of constants.

SCREEN_WIDTH Width of the graphics screen in pixels

SCREEN_HEIGHT Height of the graphics screen in pixels

SCREEN_MAX_X Maximum X co-ordinate on the screen

SCREEN_MAX_Y Maximum Y co-ordinate on the screen

SCREEN_NUM_COLORS Number of colours on the screen

SCREEN_NUM_PAGES The number of screen display pages

You should use these constants in your program rather than explicit values, as they improve the portability and readability of your programs.

Back To Top

Screen Paging

void screen_set_page(int page);

int screen_get_page(void);

void screen_show_page(int page);

A screen may be thought of as a page to which your programs output graphical data. On some target systems, a screens characteristics are such that there are in fact more than one available screen page to draw on. Typically only one page can be seen at a time, although any page may be drawn to. By directing output to a page that is not visible, and then making it the visible page, graphics output can be made to look smoother because you do not see the screen layout being drawn. If the target your program is using supports multiple pages then the constant SCREEN_NUM_PAGES will be defined to have a value other than 1.

Each of the JLib screen functions draws to a current page which the library keeps track of internally. In the case of targets that don't support paging, this current page is always the visible screen. The programmer can set the current output page by calling screen_set_page() with the appropriate page number. All screen output will then draw to that page. The number of the current output page can be found by calling screen_get_page(). By default, page 1 is displayed after a mode setting function. The function screen_show_page() will change the visible page to another page. Changing the displayed page does not affect the current output page (where screen functions will draw to).

Calling a page setting function with a page number of less than 1 or greater than SCREEN_NUM_PAGES is a fatal error. There is currently no function to get the current display page.


Developers Note: No targets utilising pages have yet been implemented. I plan to write some fake paging code so that all targets will be able to be treated as though they have several (probably two minimum) pages.


Back To Top

Screen Manipulation

void screen_clear(void);

void screen_fill(UBYTE colour);

void screen_wait_vsync(void);

These functions are designed for elementary manipulation of the screen. The function screen_clear() will fill the entire screen with the colour of the background, clearing any previously drawn graphics from it. This function is always called automatically by a screen_set_video_mode() call.

The function screen_fill() fills the entire screen with the given colour, erasing all previously drawn graphics. This function will not change the border colour of the screen (On targets where this is applicable). See Screen Functions: Palette for more information on how colours are used in JLib.

The function screen_wait_vsync() is designed to allow screens to be updated while the screen redrawing beam or raster is off screen or in the retrace period. Updates made during this time are generally smoother because the raster does not pass the drawing output process resulting in a momentarily sheared image. This function is implemented as an empty routine on some targets where retrace checking is not possible. To use the function, place a call to it before any screen blitting function. The function will wait until the retrace period before returning. This wait can slow graphics operations down, and is more noticeable on slower graphics cards.

Back To Top

Palette Overview

A palette in JLib is an array of colours specified by 8 bit RGB (red, green and blue component) values. Each colours red, green, and blue component is given in order before the next, giving a palette array of UBYTES. Each palette entry is referred to by its index into the palette. Thus, colour number zero is defined by the first three bytes of a palette. The RGB values of a colour in a palette may be changed to provide effects like fading, glowing or cycling as in fire or plasma effects.

Depending on the target, your program has SCREEN_NUM_COLORS colours available for use, numbered from 0 to (SCREEN_NUM_COLORS-1). For all modes and targets, colour 0 corresponds to the background and border colour of the screen. In many cases this colour will be black (RBG 0:0:0), although it may be changed any colour. Colours 15 and 255 (In 256 colour modes) are used for the mouse cursor by default, so changing these colour entries will change the colour of the mouse pointer if one is visible. This behaviour came about through a feature in MS-DOS that I am not capable of changing yet, so it is an impromptu standard that looks likely to stay.

JLib screen palette functions are output oriented in that they do not change any parameters passed to them. Setting or fading a palette corresponds to changing the screen palette, and does not change the colour specifications held in the passed palette array. Changes that you make to a palette array are reflected on the screen only if the array is passed to a palette function that sets the palette. Changing a colour using one of the palette functions affects the screen immediately, you do not have to redraw the screen to see the effect.

Screen Palette Functions

void screen_put_pal(UBYTE col,UBYTE red,UBYTE green,UBYTE blue);

void screen_block_set_pal(UBYTE *pal);

void screen_blank_pal(void);

void screen_fade_in_pal(UBYTE *pal,unsigned int delay);

void screen_fade_to_pal(UBYTE *pal1, UBYTE *pal2,unsigned int delay);

void screen_fade_out_pal(UBYTE *pal,unsigned int delay);

The function screen_put_pal() takes a colour number and an RGB specification and sets the colour of that index to that specification. screen_block_set_pal() takes a whole palette array as an argument and sets all SCREEN_NUM_COLORS colours at once. This is usually significantly faster than individually changing each palette entry using screen_put_pal(). You must pass this routine an array which is big enough to hold SCREEN_NUM_COLORS indexes. You can't set only half of the palette by passing a shorter array (trying this will probably result in a memory protection or corruption error).

The function screen_blank_pal() sets the whole palette to black. This can be useful when building up a complex screen image which can then be faded in smoothly. The functions screen_fade_in_pal() and screen_fade_out_pal() are provided to allow smooth fading of palettes to and from black. To fade from one palette to another you can use the function screen_fade_to_pal(). The effect of the delay parameter is currently target dependant, although this may change. Values from 1-10 seem generally appropriate.


Developers Note: More palette functions are planned, in particular: screen_fade_to_white(), screen_fade_from_white(), screen_collapse_pal(), and palette conversion functions such as colour reduction, conversion to grey scale, fade to blue/red/green, increase contrast, invert etc.


Back To Top

Non-Screen Palette Functions

Other palette functions are available to JLib programs that do not affect the screen output directly. These functions are prefixed by pal_, and generally involve manipulating palettes without producing any visible change on screen. This is useful for loading, converting between palettes, collapsing palettes and similar functions.

UBYTE *pal_load(char *fname);

UBYTE *pal_load_fp(FILE *fp);

To load a palette from a file you can use the function pal_load() which returns a palette read from the file fname, or NULL if an error occurred while reading in the palette file. You can load a palette from a file which is already open with the function pal_load_fp(). If you use this function you will have to close the file containing the palette yourself, and the file must be positioned at the correct place to begin reading the palette from. Palette files are simple dumps of palette arrays with no header information in the file.

void pal_to_grey(UBYTE *pal);

void pal_to_red(UBYTE *pal);

void pal_to_green(UBYTE *pal);

void pal_to_blue(UBYTE *pal);

These functions take the palette pal and return it with each RGB colour converted to a grey, red, green, or blue scale representation of the colour.

UBYTE pal_closest_color_rgb(UBYTE *pal,UBYTE r,UBYTE g,UBYTE b);

This function returns the colour index in pal that most closely represents the RGB specification given by r, g and b. This function will not return 0 unless pal is NULL, as mapping a colour to colour zero could later cause the colour to be shown as transparent (e.g. in sprites), rather than a solid colour.

Back To Top

Screen Blitting

void screen_blit_buff_to(int x,int y,buffer_rec *buff,int sx1,int sy1,int sx2,int sy2);

void screen_blit_buff_toNC(int x,int y,buffer_rec *buff,int sx1,int sy1,int sx2,int sy2);

void screen_blit_fs_buffer(buffer_rec *sbuff);

Screen blitting functions are the primary way to get graphics onto the screen using JLib, so you should get to know them well. The basic idea is that these functions copy rectangular areas from buffers on to the screen. Anything that you would like to be seen on the screen should be first drawn to a buffer and then blitted to the screen.

The function screen_blit_buff_to() and its non-checking counterpart are designed for blitting buffers that are not the same size as the screen. Buffers of this nature are often used for windowing, scrolling, or when a screen is made up of several parts that are updated at different times. The functions take the screen x and y co-ordinates to place the top left hand corner of the source buffer at, a pointer to the buffer in question, and co-ordinates describing the part of the source buffer that is to be copied. These source co-ordinates are the top left hand and bottom right hand corners of the source rectangle to be copied.

If the co-ordinates given fall outside of the range of the screen or buffer dimensions then clipping will occur (provided the NC function is not used). If this happens, only the part of the source buffer (if any) that falls on the screen will be blitted across.

If you are working with a buffer that is the same size as the screen, then you can gain a faster blit by using the function screen_blit_fs_buffer(). Depending on the target, this call will usually result in the fastest possible copying to the screen due to specific optimisations and assumptions about the size of the buffer. This function copies the buffer to screen position 0,0. Screen sized buffers can be treated just like a screen in your application, and blitted to the output screen as updates occur.

It is important to remember that copying a buffer to a screen will probably be the slowest part of your program, due to the big difference in speed between system memory and video memory, coupled with bus bottlenecks. See the section Performance: Increasing Speed for more information on minimising the amount of blitting your program does.

Back To Top

Next Section: Buffer Functions

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