COMMENT @%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

        Copyright (c) GeoWorks 1991 -- All Rights Reserved

PROJECT:        PC GEOS
MODULE:         
FILE:           saver.def

AUTHOR:         Adam de Boor, Mar 15, 1991

REVISION HISTORY:
        Name    Date            Description
        ----    ----            -----------
        Adam    3/15/91         Initial revision


DESCRIPTION:
        Definitions for generic screen-saver library.
                
        $Id: saver.def,v 1.1 97/04/04 14:24:15 newdeal Exp $

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%@

SetDef  __SAVER

StartLibrary    saver

;==============================================================================
;
; Library functions provided by the generic saver library
;
;==============================================================================

global	SaverCreateLaunchBlock:far
global	SAVERCREATELAUNCHBLOCK:far		; C stub
;
;	Create an AppLaunchBlock to load the given screen saver as the master
;	saver.
;
;	Pass:	bp	= disk on which saver is located
;		cx:dx	= path to saver
;	Return:	bx	= AppLaunchBlock handle
;	Destroyed:	ax
;


global	SaverDuplicateALB:far
global	SAVERDUPLICATEALB:far			; C stub
;
;	Duplicate an AppLaunchBlock.
;
;	Pass:	bx	= handle of block to duplicate
;	Return:	dx	= old handle
;		bx	= new handle
;	Destroyed:	nothing
;


;==============================================================================
;
; Random number generator
;
;==============================================================================

global	SaverSeedRandom:far
global	SAVERSEEDRANDOM:far			; C stub
;
;	Create or reset a random number generator.
;
;	Pass:	dxax	= 32-bit seed
;		bx	= RNG to reset, or 0 to create a new one
;	Return:	bx	= token for random number generator, to be passed to
;			  SaverRandom and SaverEndRandom
;

global	SaverRandom:far
global	SAVERRANDOM:far			; C stub
;
;	Return a random number in the passed range.
;
;	Pass:	dl	= max for returned number
;		bx	= random number generator
;	Return:	dx	= random number between 0 and DL-1
;	

global	SaverEndRandom:far
global	SAVERENDRANDOM:far			; C stub
;
;	Destroy a random number generator.
;
;	Pass:	bx	= random number generator
;	Return:	nothing
;

;==============================================================================
;
; Password encryption
;
;==============================================================================

global	SaverCryptInit:far
global	SAVERCRYPTINIT:far			; C stub
;
;	Create a simple encryption machine.
;
;	Pass:	ds:si	= key (null-terminated)
;	Return:	bx	= token for machine
;

global	SaverCryptEncrypt:far
global	SAVERCRYPTENCRYPT:far			; C stub
;
;	Encrypt a block of cleartext using a particular machine.
;
;	Pass:	ds:si	= text to encrypt
;		cx	= # bytes
;		bx	= token returned by SaverCryptInit
;	Return:	ds:si	= overwritten
;

global	SaverCryptDecrypt:far
global	SAVERCRYPTDECRYPT:far			; C stub
;
;	Decrypt a block of ciphertext using a particular machine.
;
;	Pass:	ds:si	= text to decrypt
;		cx	= # bytes
;		bx	= token returned by SaverCryptInit
;	Return:	ds:si	= overwritten
;

global	SaverCryptEnd:far
global	SAVERCRYPTEND:far			; C stub
;
;	Finish using an encryption machine.
;
;	Pass:	bx	= token for machine to nuke
;	Return:	nothing
;

;==============================================================================
;
; SaverVector abstraction
;
;==============================================================================

SaverVectorReflectType etype word
    SVRT_BOUNCE		enum	SaverVectorReflectType	; Elastic bounce (delta
							;  becomes -delta)
    SVRT_RANDOM		enum	SaverVectorReflectType	; Reflect in a random
							; direction opposite the
							; current one.
    SVRT_STOCHASTIC	enum	SaverVectorReflectType	; Random spot within
							; bounds.
							; Ignores delta.

SaverVector	struct
    ; Data for current location
    SV_point	word			; Current point
    SV_min	word			; Minimum value for SV_point
    SV_max	word			; Maximum value for SV_point
    SV_reflect	SaverVectorReflectType	; Type of reflection to happen when
					;  SV_point reaches a boundary
    ; Data for delta value
    SV_delta	sword			; Current delta
    SV_deltaBase byte			; Base value for delta.
    SV_deltaMax	byte			; Maximum value for delta (above base)
SaverVector	ends

global	SaverVectorInit:far
global	SAVERVECTORINIT:far			; C stub
;
;	Initialize a SaverVector structure
;
;	Pass:	es:di	= SaverVector to initialize
;		ax	= SaverVectorReflectType
;		cx	= minimum value
;		dx	= maximum value
;		bl	= delta max
;		bh	= delta base
;		si	= random number generator to use
;	Return:	nothing
;

global	SaverVectorUpdate:far
global	SAVERVECTORUPDATE:far			; C stub
;
;	Update a SaverVector according to its delta, etc.
;
;	Pass:	ds:si	= SaverVector to advance one step.
;		bx	= random number generator to use, if not SVRT_BOUNCE
;	Return:	ax	= the new coordinate.
;		carry	= set if delta changed.
;

;==============================================================================
;
; Saver fades and other fun stuff
;
;==============================================================================

;
; The different speeds supported for fades
;
SaverFadeSpeed		etype	word
SAVER_FADE_SLOW_SPEED		enum SaverFadeSpeed
SAVER_FADE_MEDIUM_SPEED		enum SaverFadeSpeed
SAVER_FADE_FAST_SPEED		enum SaverFadeSpeed

SaverWipeTypes	record
    :12
    SWT_LEFT:1			;TRUE: wipe from left
    SWT_TOP:1			;TRUE: wipe from top
    SWT_RIGHT:1			;TRUE: wipe from right
    SWT_BOTTOM:1		;TRUE: wipe from bottom
SaverWipeTypes	end

global	SaverFadePatternFade:far
global	SAVERFADEPATTERNFADE:far			; C stub
;
;	Fade a rectangle to a color, 0% -> 100% patterns
;
;	Pass:	(ax,bx,cx,dx) - rectangle to fade
;		di - handle of GState
;		si - SaverFadeSpeed (very slow, slow, medium, fast)
;	Return:	none
;

global	SaverFadeWipe:far
global	SAVERFADEWIPE:far			; C stub
;
;	Fade a rectangle to a color by wiping from one or more directions
;
;	Pass:	(ax,bx,cx,dx) - rectangle to fade
;		di - handle of GState
;		si - SaverFadeSpeed (very slow, slow, medium, fast)
;		bp - SaverWipeTypes for sides to use
;	Return:	none
;

SaverBitmapMode		etype word
SAVER_BITMAP_CENTER		enum SaverBitmapMode
SAVER_BITMAP_TILE		enum SaverBitmapMode
SAVER_BITMAP_UPPER_LEFT		enum SaverBitmapMode
SAVER_BITMAP_APPROPRIATE	enum SaverBitmapMode

global	SaverDrawBGBitmap:far
global	SAVERDRAWBGBITMAP:far			; C stub
;
;	Draw a background bitmap to the window
;
;	Pass:	di - handle of GState
;		(cx,dx) - width, height of window
;		ax - SaverBitmapMode
;		bx - VM file handle
;	Return:	carry - set if error
;

;==============================================================================
;
; SuperClass of the generic saver thread.
;
;==============================================================================
SaverClass      class   GenProcessClass

SaverClass      endc

;==============================================================================
;
; Other object classes that can be of use.
;
;==============================================================================

SaverApplicationClass	class	GenApplicationClass

SaverLockMode	etype	word, 0
    SLM_AUTOMATIC	enum	SaverLockMode	; Lock screen on save whenever
						;  password is valid
    SLM_MANUAL		enum	SaverLockMode	; Lock screen only when Lock
						;  Screen trigger is clicked.

SaverInputOptions	record
    SIO_REDUCE_PRIORITY:1	;TRUE: reduce priority when running
    SIO_NEVER_ON:1		;TRUE: prevent blanking when in lower right
    SIO_CONSUME_KEYPRESSES:1	;TRUE: keypresses are consumed when unblanking
    :5				;pad to byte
SaverInputOptions	end

SaverWakeupOptions	record
    SWO_MOUSE_MOVE:1		;TRUE: wake on mouse moves
    SWO_MOUSE_PRESS:1		;TRUE: wake on mouse presses
    SWO_KEY_PRESS:1		;TRUE: wake on keypresses
    :5
SaverWakeupOptions	end

SaverModeFlags	record
    SMF_USE_NETWORK:1		;TRUE: use network for passwords
    SMF_CANT_LOCK:1		;TRUE: no password available, so keep
				; Lock Screen triggers unusable
    :6
SaverModeFlags	end

SAVER_MAX_PASSWORD	equ	20	; Max length of password.


SaverExtraData	record		; value passed in ALB_extraData
    SED_NOT_JUST_TESTING:1		; if set, saver was started from
					;  Preferences and should replace any
					;  running one if SED_SAVER_ID is
					;  0.
    SED_SAVER_ID:15			; ID number for this saver
SaverExtraData	end

MSG_SAVER_APP_START			message	
; Message sent to get us to start saving the screen. It must not be sent
; if this isn't the master saver, as it does various things that are not
; overly compatible with being an inferior saver.
;
; Context:	This is sent by the input-manager thread when it detects
;		the proper amount of time has passed without any input
;		having been received from the user.
; Source:	Input Manager
; Destination:  SaverApplication object
; Interception: Not usually intercepted. Intercept MSG_SAVER_APP_SET_WIN
;		to initialize things and begin drawing.
;
; Pass:
;		nothing
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_STOP			message	
; Message sent to get us to stop saving the screen. It must not be sent
; if this isn't the master saver, as it does various things that are not
; overly compatible with being an inferior saver.
;
; Context:	This is sent by the input-manager thread when it detects
;		user input after it has told us to save the screen.
; Source:	Input Manager
; Destination:  SaverApplication object
; Interception: Not usually intercepted. Intercept MSG_SAVER_APP_UNSET_WIN
;		to shut things down, instead.
;
; Pass:
;		nothing
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_SET_PARENT_WIN	message	
; Set the window on which to open the main screen-saving window.
;
; Context:	Sent on attach, but may also be sent by a multi-module
;		screen saver that wishes to control this one.
; Source:	SaverApplicationClass
; Destination:  SaverApplicationClass
; Interception: Unlikely. The default handler will also fetch the bounds
;		of this window and invoke MSG_SAVER_APP_SET_BOUNDS on itself,
;		passing (0,0), (width, height).
;
; Pass:		bp	= handle of window
;		
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_SET_BOUNDS	message	
; Specify the bounding rectangle of any drawing operations. Normally set to the
; bounds of the parent window.
;
; Context:	Sent by SaverApplication when it is attached as the master
;		saver, but may also be sent by a master saver to restrict
;		a compliant saver to a certain portion of the window
;		it is passed in MSG_SAVER_APP_SET_WIN. It might do this
;		if it wanted to overlap the output of two screen savers,
;		for example.
; Source:	SaverApplication, master saver
; Destination:  SaverApplication object
; Interception: Not generally intercepted. Default handler simply sets
;		SAI_bounds, so no need to pass to superclass if you already
;		do that.
;
; Pass:
;		ss:bp	= Rectangle (within coordinates of window that will
;			  eventually be opened)
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_SET_WIN	message	
; Specify a window and graphics state the saver should use when drawing. If
; the app already had a window registered, it is overwritten and the previous
; associated gstate is destroyed.
;
; Context:	Sent by SaverApplication in its MSG_SAVER_APP_START handler,
;		but may be sent by a master saver. The saver should not use
;		any graphics states or windows other than the ones passed
;		here.
; Source:	SaverApplication, master saver
; Destination:  SaverApplication object
; Interception: Should be intercepted to set up whatever timers or other
;		data are required to actually draw stuff to the screen.
;		You must pass this to the superclass to have the 
;		SAI_curWindow and SAI_curGState instance variables set.
;
; Pass:
;		dx	= handle of open window
;		bp	= handle of gstate for drawing to it.
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_DISPATCH_EVENT_IF_MINE	message	
; Dispatch a recorded event to oneself if the saverID passed matches one's own.
;
; Context:	Used exclusively by an uebersaver that needs to control a
;		gaggle of other screen savers. Typically the uebersaver
;		will pass a unique number in the ALB_extraData field for each
;		inferior saver it launches, then use this to send messages
;		to the application object via IACP.
; Source:	A controlling screen saver
; Destination:  SaverApplication object
; Interception: Should not be intercepted.
;
; Pass:
;		cx	= handle of recorded message to dispatch
;		dx	= ID against which to compare SAI_saverID. If
;			  there's a match, the recorded message should
;			  be dispatched, else it should be destroyed.
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_GET_WIN_COLOR	message	
; Fetch the background color to use for the window about to be opened.
;
; Context:	Sent by SaverApplication when opening a window in which
;		it will draw.
; Source:	SaverApplicationClass
; Destination:  SaverApplicationClass
; Interception: Intercept if you want some other window type other
;		than a plain (i.e. no expose events) black one.
;
; Pass:
;		nothing
; Return:
;		ax	= WinColorFlags
;		cx, dx, bp - unchanged
;

MSG_SAVER_APP_GET_WIN_ODS	message	
; Fetch the optrs that should be given to WinOpen when creating the window
; into which the saver will draw.
;
; NOTE: If you return the application object as the input or exposure optr,
; you must be sure to intercept *all* messages that might come to the app
; object as a result, as some will go into an infinite recursion (most
; notably MSG_META_RAW_UNIV_ENTER) if allowed to make their way up to the
; SaverApplication level.
;
; Context:	Sent by SaverApplication when opening a window in which it
;		will draw.
; Source:	SaverApplicationClass
; Destination:  SaverApplicationClass
; Interception: Intercept if you want to receive expose events (you will also
;		need to intercept MSG_SAVER_APP_GET_WIN_COLOR to turn off the
;		WCF_PLAIN bit) or mouse input (you will need to alter
;		SAI_inputOptions appropriately to avoid getting shut off when
;		the user moves the mouse).
;
; Pass:
;		nothing
; Return:
;		^lcx:dx	= input object for the window
;		^lax:bp	= exposure object for the window
;

MSG_SAVER_APP_UNSET_WIN		message	
; Revokes permission to use the window and gstate passed in
; MSG_SAVER_APP_SET_WIN
;
; Context:	Sent by SaverApplication when it receives MSG_SAVER_APP_STOP,
;		or by a master saver when it no longer wants you to
;		draw to the screen.
; Source:	SaverApplication, master saver
; Destination:  SaverApplication object
; Interception: Intercept if you have things you need to clean up before you
;		stop drawing.
;
; Pass:
;		dx	= handle of window being unset. Window will not
;			  be unset unless it is the window most recently
;			  set with MSG_SAVER_APP_SET_WIN
; Return:
;		carry set if window unset:
;			dx	= window handle that was being used
;			bp	= gstate handle that was being used
;		carry clear if window not unset
;			dx	= window handle that was being used
;			bp	= gstate handle that was being used
;		ax, cx - destroyed
;

MSG_SAVER_APP_SAVE_SCREEN_TRIGGER_CREATED	message	private
MSG_SAVER_APP_LOCK_SCREEN_TRIGGER_CREATED	message	private
; Take note that one of the two triggers we asked to be created by an
; express menu has been created and initialize it appropriately.
;
; Context:	Sent by an ExpressMenuController after we've sent it
;		a MSG_EXPRESS_MENU_CONTROL_CREATE_ITEM
; Source:	ExpressMenuControlClass
; Destination:  SaverApplicationClass
; Interception: Not likely.
;
; Pass:
;		ss:bp	= CreateExpressMenuControlItemResponseParams
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_FORCE_SAVE	message	
; Forcibly save the screen, after a suitable delay to allow the user to remove
; his/her hand from the mouse.
;
; Context:	Sent by one of our Save Screen triggers
; Source:	A Save Screen trigger in an express menu.
; Destination:  SaverApplication
; Interception: Not usually intercepted.
;
; Pass:
;		nothing
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_FORCE_LOCK	message	
; Forcibly lock the screen, after a suitable delay to allow the user to remove
; his/her hand from the mouse. If no password exists, it will produce an
; error box telling the user this.
;
; Context:	Sent by one of our Lock Screen triggers
; Source:	A Lock Screen trigger in an express menu.
; Destination:  SaverApplication
; Interception: Not usually intercepted.
;
; Pass:
;		nothing
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_CHANGE_SAVER_IF_NOT_ME	message	
; Launch the saver indicated in the passed AppLaunchBlock, if it's not us, then
; exit.
;
; Context:	Sent by preferences when the user changes screen savers.
; Source:	Preferences
; Destination:  SaverApplication
; Interception: Not usually. If the AppLaunchBlock is indeed for a different
;		saver, this will send MSG_SAVER_APP_CHANGE_SAVERS to itself,
;		which is a much better message to subclass.
;
; Pass:
;		^hcx	= AppLaunchBlock for new master saver. Will be freed
;			  once this method returns, so if it needs to be
;			  used later, it must be copied.
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_CHANGE_SAVERS	message	
; Launch a different screen saver (defined by the passed AppLaunchBlock) and
; exit.
;
; Context:	Sent by default handler for MSG_SAVER_APP_CHANGE_SAVER_IF_NOT_ME
;		when it finds the AppLaunchBlock isn't it.
; Source:	SaverApplicationClass
; Destination:  SaverApplicationClass
; Interception: If a subclass manages additional savers, it should make them
;		all go away before passing this message on to the superclass,
;		to avoid problems with non-multi-launchable screen savers,
;		if such there be.
;
; Pass:
;		^hcx	= AppLaunchBlock for new master saver
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;
MSG_SAVER_APP_CHECK_PASSWORD	message
; Check the password that the user entered, and if it's valid then unsave
; the screen (and remove the sys-modal password dialog).
;
; Context: 	Sent by the password text object when user hits CR.
;
; Source:	anybody
; Destination:  SaverApplicationClass
; Interception: unlikely
;
; Pass:
;		nothing
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_LOCK_SCREEN	message	
; Put up something to keep the user from getting access to the computer until
; s/he enters the proper password.
;
; Context:	Sent when screen saver is told to stop if SSF_LOCK_SCREEN bit
;		is set.
; Source:	SaverApplication
; Destination:  SaverApplication
; Interception: Must always call superclass at some point, unless you've
;		completely redone the lock screen support.
;
; Pass:
;		nothing
; Return:
;		nothing
;		ax, cx, dx, bp - destroyed
;

MSG_SAVER_APP_UNLOCK_SCREEN	message	
; Remove the dialog that's up on the screen preventing the user from getting
; useful work accomplished.
;
; Context:	Sent when a password has successfully been entered, or if
;		the screen saver kicks in while the lock-screen dialog is
;		up. It will be sent on MSG_SAVER_APP_START only if
;		SSF_SCREEN_LOCKED is set in SAI_state.
; Source:	SaverApplication
; Destination:  SaverApplication
; Interception: Must always call superclass at some point, unless you've
;		completely redone the lock screen support.
;
; Pass:
;		nothing
; Return:
;		nothing
;		bp - unchanged
;		ax, cx, dx - destroyed
;


TEMP_TESTER_OBJECT		vardata	optr
; The SaverTester object instantiated to receive input events from the
; opened window when testing.
; 
	noreloc TEMP_TESTER_OBJECT

SaverStateFlags	record
    SSF_LOCK_SCREEN:1		; non-zero if user has chosen to lock the
				;  screen
    SSF_JUST_TESTING:1		; non-zero if just testing the saver and
				;  should exit when done.
    SSF_SCREEN_LOCKED:1		; non-zero if lock-screen dialog is up and
				;  must be taken down after screen is saved.
    :13
SaverStateFlags	end

    SAI_lockMode	SaverLockMode		SLM_MANUAL
    SAI_inputOptions	SaverInputOptions	0
    SAI_wakeupOptions	SaverWakeupOptions	mask SWO_MOUSE_MOVE or \
						mask SWO_MOUSE_PRESS or \
						mask SWO_KEY_PRESS
    SAI_password	byte	SAVER_MAX_PASSWORD dup(?)
    SAI_passwordLen	word	0		; # bytes in there.
    SAI_parentWin	hptr.Window		; handle of window on
						;  which to open our main
						;  saver window.
		noreloc	SAI_parentWin
    SAI_curWindow	hptr.Window		; Window in which we're
						;  displaying things
		noreloc SAI_curWindow
    SAI_curGState	hptr.GState		; Cached graphics state for
						;  displaying things
		noreloc	SAI_curGState
    SAI_bounds		Rectangle

    SAI_saverID		word	0		; Value passed in ALB_extraData,
						;  for use in MSG_SAVER_APP_-
						;  DISPATCH_EVENT_IF_MINE
SID_MASTER_SAVER	equ	0		; if SAI_saverID is 0,
						;  this is the master saver.
						; if SAI_saverID is non-zero,
						;  we abdicate much of our
						;  responsibility.
SID_DYING_SAVER		equ	-1		; ID used when a master saver
						;  gets told to change to
						;  a different master saver.
						;  This prevents having two
						;  master savers registered
						;  at once..

SAExpressMenu	struct
    SAEM_emc		optr		; the controller itself
    SAEM_saveTrigger	optr		; The Save Screen trigger
    SAEM_lockTrigger	optr		; The Lock Screen trigger
SAExpressMenu	ends

    SAI_expressMenus	lptr.ChunkArrayHeader	; Array to keep track of
						;  express menus so we can
						;  set the lock screen
						;  trigger usable or not
						;  depending on what the
						;  user does in Preferences
    SAI_state		SaverStateFlags 0
    SAI_mode		SaverModeFlags	0	; on the network?

    SAI_passwordBlock	hptr			; password dialog resource

SAOptionDesc	struct
    SAOD_key	nptr.char		; pointer to the key to use
    SAOD_size	byte			; size of integer to fetch
    SAOD_offset	word			; offset in instance data into which
					;  to place the result
SAOptionDesc	ends

SAOptionTable	struct
    SAOT_category	nptr.char	; category for options
    SAOT_numOptions	word		; number of integer options to fetch
    SAOT_options	label	SAOptionDesc
SAOptionTable	ends

global	SaverApplicationGetOptions:far
global	SAVERAPPLICATIONGETOPTIONS:far			; C stub
;
;	Pass:	es:bx	= SAOptionTable
;		*ds:si	= SaverApplication object
;	Return:	nothing
;

SaverApplicationClass	endc



EndLibrary      saver
