SDSDL: GEM video driver for SDL                            v1.0.1, 29 May 2012
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  SDSDL is a GEM/3 video driver, ported from the original C/assembly mix to 
C, and displaying its output on an SDL surface. 

In use
~~~~~~

  There are two ways to call driver functions. One is sd_dispatch(), which
emulates the single entry point of a 16-bit GEM driver. You pass in a 
populated GSXPB structure, and SDSDL interprets it, and populates the 
appropriate result values. 

  The other method is to call individual functions by name. They're listed
in sdsdl.h; for the most part, their prototypes are similar to the standard C
bindings for the GEM VDI.

SDSDL control functions
~~~~~~~~~~~~~~~~~~~~~~~

  These functions have no counterparts in GEM, but are necessary to interface
with the driver.

int sd_handle_event(unsigned handle, EVPTR ev);

	SDSDL does not have an event handling thread. This must be operated
	by the calling code, and keyboard and mouse events passed to SDSDL
	using this function. 'handle' is the handle of the workstation 
	(returned by sd_opnwk); 'ev' points to an SDL event. If the event is 
	handled by SDSDL, returns nonzero; otherwise zero.

void sd_setwidth(unsigned w);
void sd_setheight(unsigned h);

	Set the dimensions of the screen (default is 640x480).

void sd_setplanes(unsigned np);

	Set the colour depth of the screen as GEM will see it: 1-15 planes. 
	Default is 15, for a truecolour display.

void sd_setsurface(PSURFACE s, PRECT window);

	If this is called, SDSDL will render into the specified rectangle on 
	the specified surface. Otherwise, opening a workstation will create a 
	new SDL window for output.

The above four functions should be called before the workstation is opened.

Use of SDSDL through API
~~~~~~~~~~~~~~~~~~~~~~~~

  Call sd_opnwk to initialise SDSDL. Pass the address of an unsigned integer
to 'handle'; this handle should then be used when calling other functions.
The API is modelled on the standard C bindings for the GEM VDI, except that 
all function names begin sd_.

  Some functions to note:

void sd_updwk(unsigned handle) 

		-- in the original GSX model, you could not be sure the screen 
		   was updated until this function was called. In practice, no 
		   GEM applications use it; they expect the screen to be 
		   updated immediately after each drawing function is called. 

		   In SDSDL it calls SDL_UpdateRect() for the screen area.

void sd_clear_disp_list(unsigned handle)
void sd_bit_image(unsigned handle, unsigned len_filename,
	unsigned *filename, 
	unsigned aspect, unsigned xscale, unsigned yscale,
	unsigned h_align, unsigned v_align, signed xy[])

		-- These two functions are not implemented; in GEM, they are
		   only present in printer drivers.

unsigned sd_spalette(unsigned handle, unsigned palette)

		-- Whatever the value of 'palette', resets the screen 
		   colours to their default values.

unsigned sdrq_valuator(unsigned handle, unsigned val_number, unsigned value,
				unsigned *val_out, unsigned *term,
				unsigned *status)

		-- Valuator input is not supported.

unsigned sdrq_choice  (unsigned handle, unsigned chc_number, unsigned value,
				unsigned *val_out, unsigned *status)

		-- Choice input corresponds to waiting for a function key to
		  be pressed.

Use of SDSDL through dispatching
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  To use SDSDL through sd_dispatch(), you will need to initialise a GSXPB 
structure:

typedef struct gsxpb
{
	GSXCTRL *contrl;
	unsigned *intin;
	signed *ptsin;
	unsigned *intout;
	signed *ptsout;
} GSXPB;

The first entry, 'contrl' should point at a GSXCTRL structure:

typedef struct gsxctrl
{
	unsigned function;
	unsigned ptsin_count;
	unsigned ptsout_count;
	unsigned intin_count;
	unsigned intout_count;
	unsigned subfunction;
	unsigned handle;
	void *ptr1;
	void *ptr2;
	void *ptr3;
	unsigned extra[5];
} GSXCTRL;

In GSXCTRL:
	'function' is the GEMVDI function number, 1-39, 100-132 or 1000.
	'ptsin_count' is the number of points provided in the 'ptsin' member
		of GSXPB.
	'ptsout_count' will be populated by SDSDL on return with the number 
		of points written to the 'ptsout' member of GSXPB. 'ptsout' 
		should be at least 12 integers long.
	'intin_count' and 'intout_count' are the same, for the 'intin' and
		'intout' arrays. 'intout' should be at least 128 unsigned 
		integers.
	'subfunction' is used for the Escape and General Drawing Primitive
		functions.
	'handle' is the workstation handle. It is populated by SDSDL when
		the 'Open Workstation' (call 1) or 'Open Virtual Workstation'
		(call 100) succeeds. For all other calls a valid handle must
		be passed in here.
	
The other members of GSXCTRL only apply in particular functions:
	'ptr1' / 'ptr2' : Used in bit blits (functions 109, 110, 121) to 
		hold pointers to the source and destination MFDBs (bitmaps).
		Also used when exchanging timer and mouse callback vectors; 
		'ptr1' holds the new vector, and on return 'ptr2' will hold 
		the previous one. 

		'ptr1' is also used when loading / unloading fonts (functions
		119 and 120); it points at the head of the font chain to 
		load or unload.

		'ptr2' is used when loading fonts (function 119); it points 
		to a text rendering buffer whose size is given by extra[0].

	'ptr3' is used when loading fonts (function 119); it is a pointer to
		a font manager callback used to page fonts into memory.

		void (*FONTMGRFUNC)(struct font_head *pf);

	'extra' holds extra integer parameters, and is used by three 
		functions:
			10 (write cell array):	extra[0] = length of a row
						extra[1] = elements per row
						extra[2] = number of rows
						extra[3] = write mode
			27 (query cell array):	extra[0] = length of a row
						extra[1] = number of rows
						extra[2] = elements used / row
						extra[3] = rows used
						extra[4] = error flag
			119 (load fonts)	extra[0] = bytes in text buffer

Recent changes
~~~~~~~~~~~~~~

1.0.1: Various bugfixes, mainly to handle crashes or rendering problems when 
      the driver is told to draw partly offscreen.


Legal bits
~~~~~~~~~~

SDSDL: GEM video driver for SDL
Copyright 2012 John Elliott <jce@seasip.demon.co.uk>
Based on SDPSC9.VGA copyright 1987, 1999 Caldera Thin Clients, Inc.

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

