Graphic import/export filters for OPL
-------------------------------------

Introduction:

  The native image format on S3a computers is the PIC format.
  To access other formats import/export filters are required.

  At present, the following formats are supported by filter modules:
  BMP, GIF, PCX.

  The filter modules are part of the PicPoc and PocView applications
  but can be used in user written applications, too.

  You are allowed to use these filter modules free of charge within
  your own private applications for noncommercial purposes only.



--------------  Interface specification -------------------------------------------

  This specification applies to the filter modules BMP.OPO, GIF.OPO, and PCX.OPO
  found in PicPoc V2.63 upwards and PocView V1.43 upwards.



IMPORT
======

  The filters support 2 import modi:

  - Open mode:  The imported image determines the number of planes (1 or 2)
  - Place mode: The application determines the number of planes ( 1 or 2)


ret% = loadbit%:(file$,selec%,mode%,acntrl%,ahandle%)

file$	= 	filename of file to import
		(full path name with extension)

selec%	= 	plane selector (planes wanted)
			place mode:	1   black only
					2   grey only
					3   both
			open mode:	3
				
mode%	= 1	place mode (create drawable that can be placed on target drawable)
	  0	open mode (create stand alone drawable)

	  16    diffusion dither (Floyd-Steinberg)
	  32    no dither
	  0     2x2 dither

	  256	importing process unvisible (for slide shows / background operation)
	  0	importing process visible (for normal import)

	  You can combine these values.


acntrl%	= 	address of control area of the following consecutive fields

		planes%  = # planes (in/out)
			place mode: (in) number of planes in target drawable
			open mode:  (out) number of planes in resulting drawable
			
		redfac% = reduction factor (in/out)
			0 = automatic (selected factor is written back)
			1,2,4,8	reduction by 1,2,4,8
					
		clpx% = x-coordinate clipping ( use 0 for no clipping)
		clpy% = z-coordinate clipping ( use 0 for no clipping)
		clpw% = with clipping	(use $7fff for no clipping)
		clph% = height clipping (use $7fff for no clipping)

ahandle%   =	address for resulting drawable handle (out)

return values:
		0	normal termintation
		<0	abnormal termination
			- 119  resulting drawable too small (height or width = 0)
			- 43   resulting drawable too large (> 256000 pixels)
			- 256  nothing to import (e.g. grey selected, but b&w image)
			- 114  user abort
			- 69   invalid file format
		all other codes as in OPL manual

Exceptions:	none

Example (using the BMP filter):

GLOBAL planes%,redfac%,clpx%,clpy%,clpw%,clph%
GLOBAL handle%

planes% = 2  rem we don't really need this in open mode
             rem in place mode this would determine the number 
             rem of planes of the resulting drawable.
redfac% = 1  rem no reduction
clpx% = 0    rem clip area (0,0) ... (640,400)
clpy% = 0
clpw% = 640
clph% = 400

ret% = loadbit%:("M:\pic\mypic.bmp",3,16,addr(planes%),addr(handle%))
rem             load both planes, open mode, diffusion dither
if ret% = 0
    guse handle% (this is our new bitmap)
endif


EXPORT
======

savebit%:(newfile$,planes%)

	newfile$	file name (full path with extension)
	planes%		number of planes in current drawable (1 or 2)

	The routine exports the current drawable (gUse).
	Width and height are determined from the drawable.

Return values:  0

Exceptions:	Errors as listed in OPL manual



Example (using the PCX filter):
-------------------------------

    guse new%
    savebit%:("m:\pic\new.pcx",2)

    exports drawable "new%". This drawable must have two planes.

--------- Contact

Berthold Daum
lichtbild pty ltd
21 Margate St
LPO Box 6011
Cromer, Vic 3193
Australia
FAX: +61-3-9584 9638
CompuServe: 100026,3365
INTERNET: lichtbild@compuserve.com
WorldWideWeb: http://ourworld.compuserve.com/hompages/lichtbild


End of Document