Amiga ISO Collection/AmigaUtilCD1.iso/GFX/Converter/DC-PGS21.DMS/in.adf/Extras/DevDocs.LHA/DeveloperDocs/help/gio.txt

Text File | 1996-06-03 | 17.9 KB | 528 lines

Programming information for .GIO files (updated 29/3/96 for Photogenics 2)
==========================================================================

Copyright © Almathera Systems Ltd 1994-6. All Rights Reserved.

All programming examples and documentation is proprietary
and may only be used to create .GIO files for use
with the Photogenics program.

Any other use of this documentation and source is strictly
prohibited. It may not be reproduced or copied without
written authorisation from Almathera.

Permission is hereby given to allow free or commercial
distribution of .GIO files for Photogenics written using
this code. Almathera encourages the free distribution
of .GIO files for use with Photogenics.

(ie. If you write a GIO, you can do whatever you want with
it!)

.GIO files may not be distributed for use with any other
Amiga software.

(ie. You can't reverse engineer our system and build your
own image-processor around our files)

---------------------------------------------------
If you have any problems developing add-on files for
Photogenics, then please contact:

Jolyon Ralph on (UK) 0181 687 0040 during office hours, or email to:

[e-mail]

or Jolyon on IRC

We'll be happy to help out where we can.

If you've come up with an excellent idea for a loader but
can't program it yourself, then let us know and we might
have a go ourselves, or call our BBS, someone may
have already written one!

-----------------------------------------------------

What is a .GIO file? - Jolyon Ralph (6/3/95)
============================================

GIO files are the 'loaders' and 'savers' that Photogenics
uses to import and export files. Unlike other programs one file
can support either loading, saving or both. Scanning, printing,
digitizing, etc. can all be done within a .GIO file.

A .GIO file is a standard system disk-based library file. You can
create .GIO files with any programming language that can create
a library (assembler, C, C++, Modula II, etc.). The examples provided
were written using SAS V6.51 and Hisoft Devpac, but any C compiler
and Assembler should be capable of compiling them with little
or no alteration to the sourcecode.

Using libraries carries little overhead and has the major advantage
that the Amiga operating system automatically handles ram cacheing
of libraries and flushing libraries when ram is low without us having
to worry about that.

Note. Several new functions have been added as of V1.2

Each library follows a standard function layout (as shown
in the gio.fd file:)

##base __GIOBase
##bias 30
##public
GioInfo()()
GioExamine(giodata)(a0)
GioRead(giodata)(a0)
GioWrite(giodata)(a0)
GioSavePrefs(giodata)(a0)    [V1.2]
GioCleanUp(giodata)(a0)        [V1.2]
GioAbout(giodata)(a0)        [V1.2]
GioStartup()()                   not implemented
GioShutDown()()              not implemented
GioLoadPrefs(giodata)(a0)    [V1.2]
##end

First a description of the functions:


GioInfo
=======

flags = GioInfo(void)
 d0.L

This is required by all .gio files. It returns flags depending on
the capabilities of the loader. The flags are (defined in gio.h)

GIOF_LOADER8 -
 The .gio file can return 1 to 8-bit data with a palette.
 (eg GIF.gio)

GIOF_LOADER24 -
 The loader can return 24-bit data.
 (eg JPEG.gio)

GIOF_SAVER8 -
 The loader can save 1 to 8-bit data  // not currently implemented!

GIOF_SAVER24 -
 The loader can save 24-bit data

GIOF_LOADFILE -
 The loader expects a filename (eg any loader that loads from files)
 Do NOT set for fractal creators, scanner drivers, etc.

GIOF_SAVEFILE -
 The saver expects a filename (eg any loader that saves to files)
 Do NOT set for printer drivers, 24-bit display devices, etc.

GIOF_PLANAR -
 Load data is supplied in Planar format (ILBM.gio)

GIOF_NOID -
 The loader is not capable of accurately identifying a file (eg
 RAW.gio, SCULPT.gio, etc.). These loaders will NOT be attempted
 for the UNIVERSAL loader. This does not have to be set if
 GIOF_LOADFILE is not set.

GIOF_NOFILEOPEN -
 By default Photogenics will open the file (using Open), read in
 the first 64-bytes (for Universal loader detection) and pass
 you the filehandle. It handles closing the file afterwards.
 This flag tells Photogenics to not do any file open operations.
 This flag requires the GIOF_LOADFILE to be set and may be ignored
 if GIOF_NOID is not set and the loader is called via the UNIVERSAL
 loader.
 This should not be used unless vital!

GIOF_LOADNOPROGRESS -  [V1.2]
 When this is selected no Progress requester is opened on calling
 GioRead()

GIOF_SAVENOPROGRESS - [V1.2]
 When this is selected no Progress requester is opened on calling
 GioWrite()

GIOF_EXTENDED - [V1.2]
 This flag must be used for all .GIO files that use any V1.2 features.

GIOF_SAVEPREFS - [V1.2]
 A preferences page is available when calling GioSavePrefs()

GIOF_LOADPREFS - [V1.2]
 A preferences page is available when calling GioLoadPrefs()

GioExamine
==========

error = GioExamine(struct GioData *giodata)
 d0.L                               A0

GioExamine is expected to return enough information about the
file to be loaded or created for memory to be allocated inside
Photogenics. At the bare minimum, this means width (in pixels)
and height (in pixels). With Photogenics V1 all buffers are
24-bit so depth is not important, although this should be set to
the minimum depth you require for future compatibility.

If GIOF_LOADFILE is set, then giodata->Data will point to
the first 64 bytes of the file, and giodata->FileHandle is
a dos.library filehandle you can use to access the file
(It is pointing at the 65th byte of the file as of
calling GioExamine, you may need to Seek yourself).

NOTE!! When MacBinary header extraction is implemented it may
not be safe to assume fixed positions in the file for seeks. We
have added another value to the header (giodata->SkipBytes)
which should be added to all Seek positions.

If GIOF_NOID is not set, then GioExamine is also expected to
determine whether the file is of the right type for the loader.
This should be done by examining the first 64-bytes of the
file (more if necessary) and not, unless absolutely unavoidable,
by comparing patterns with the filename.

DO NOT TRASH ANY VALUES IN THE GIO IF YOU HAVE NOT POSITIVELY
IDENTIFIED THE FILE. SPECIFICALLY, DO NOT WRITE TO THE giodata->Data
DATA. If you do this, and the file turns out NOT to be your
type of file, the next .GIOs that try and examine the file
will be given corrupt data. Similarly, do not mess with the filename.

If you cannot guarantee identification then set the GIOF_NOID flag
in the GioInfo() structure...

The error returned indicates what kind of error.

Normally, GioExamine() should return one of three:

GIOF_OK        - No error
GIOF_WRONGTYPE - Wrong type of file.
GIOF_ABORTED   - User selected a Cancel button on a requester

although the other errors may also be needed in some cases (see
gio.h)

If you come up with a specific error that is non-standard (for
example, an unsupported compression system) you can
bring up your own error with the following code:

    if(error_happened)
    {
        Error("Unable to load - Unsupported compression type!");
        // this opens an error requester
        giodata->Error = GIOF_ABORTED;
        goto err;         // quit out of program
    }

In this case GIOF_ABORTED is used, as this does NOT bring up
another error requester when returning to the program.

Non-File loaders (eg scanner drivers)
======================================================

You must return the dimensions of your final image from here,
so this function must contain either default fixed sizes or a call to
the pgs.library GetDimensions() call which opens a standard picture
size requester (see colournoise.c).
(There are various other functions in pgs.library that you might
find useful for getting values from the user. See the
pgs_protos.h file for prototypes to these functions.)

If writing a scanner driver or similar, the area to be scanned should
be selected in this function. You will have to write your own user
interface code to support this.


GioRead
=======

error = GioRead(struct GioData *giodata)
 d0.L                             A0

Once GioExamine has returned, memory is allocated and a buffer
set up. Photogenics 24-bit buffers are not allocated in one
contiguous lump (to make it easier to allocate memory on
if ram is fragmented or if you have seperate RAM types (eg
24-bit and 32-bit) which are not merged.

Each line of 24-bit data is allocated seperately and a table
of APTRs to each allocation is your only access method to
the data. Each line is width*3 bytes long and the
format is

   UBYTE R,G,B,R,G,B,R,G,B... and so on..

To write data to a bitmap you have to obtain a pointer to the
line (you cannot access it directly from the gio!). Only then
can you edit data in the line. Use the GetLine(giodata,linenumber)
function to lock the line, and when you have finished with it you
MUST use ReleaseLine(giodata,linenumber). You can have more
than one line allocated at once, but it is *BAD* to allocate more
lines than you really need. Never allocate all the lines for your
picture at one go! Future versions of Photogenics will use the
GetLine/ReleaseLine functions to arbitrate access to virtual memory,
and this could prevent the loader using virtual memory correctly.

To set a pixel colour at position x,y;

    byteptr =GetLine(giodata,y);        // remember to check for errors!

    if(byteptr)
    {
        byteptr+=    3*x;
        *byteptr++ = red;
        *byteptr++ = green;
        *byteptr   = blue;
        ReleaseLine(giodata,y);
    } else Error("Fatal error, couldn't get iimage data");



Obviously, if you are adding a whole row of pixels you only
need to obtain the line and release it outside your horizontal
loop and not every time you write a pixel.

GioRead() should decode data into this memory, but it does not need
to decode the format to 24-bit. Simply read the data directly in
(see how the BMP.c loader does this) and set the depth in giodata->Depth
and Photogenics will convert it to 24-bit.

Similarly, Planar formats (eg ILBM) assume that each line contains a line
of planar data (line 0 plane 0, line 0 plane 1... line 0 plane xx)
and this will be converted to chunky internally.

Non-24 bit formats must have a palette associated. It must be written
out here *NOT in GioExamine()* and giobase->Palette points to
768 bytes of memory already allocated to store up to 256 colour
registers in RRGGBB format. (range 0 to 255 per component)

You can create a prefered palette for 24-bit pictures if
you want. Palettes in IFF-24 pictures will be loaded.

Of course, you can convert to chunky/24-bit yourself if you
prefer. Make sure the GIOF_PLANAR flag is not returned in GioInfo() and
that you always return giodata->Depth equal to 24.

DO NOT SET THE giodata->Depth in GioRead to a higher value than
you set it in GioExamine!

If you want to do your own file handling (eg using fopen instead
of Open) then it is perfectly safe to open the file pointed to
in filename yourself. However you must first:

    Close(giodata->Filehandle);
    giodata->Filehandle = 0;

This also allows you to do your own asynchronous file access.
*THIS MUST ONLY BE DONE IN GIOREAD not GIOEXAMINE!!!*

GioWrite
========
At the moment Photogenics only supports 24-bit data image buffers. Future
versions will support saving 8-bit (or less) rendered data. To
protect your code from future changes, make sure you check
that you are being given 24-bit data (by checking that giodata->Depth
== 24).

You can specify that you only want to save one type (8 or
24 bit) with the GIOF_ flags.

Example 24-bit saver code is included in the BMP.c code.

If you are writing a displayer (eg for graphics cards) you do not set the
GIOF_SAVEFILE bit and you do not receive a filehandle.

If you want to do your own file handling (eg using fopen instead
of Open) then it is perfectly safe to open the file pointed to
in filename yourself. However you must first:

    Close(giodata->Filehandle);
    giodata->Filehandle = 0;

You could, of course, not set the GIOF_SAVEFILE bit, but then you'd
have to ask the user for the filename yourself. Our ANIM saver has to do this.

GioSavePrefs [V1.2]
===================
Rather than make the user select save options every time they try
and save using your .GIO, you should try and put options that the
user is unlikely to want to change every time into this function.

Make sure you add the GIOF_SAVEPREFS flag to the GioInfo() function
return value, otherwise the user will not be able to select the
"Prefs" button in the savers list.


GioLoadPrefs [V1.2]
===================
This works in the same way as GioSavePrefs(), but obviously for
options for loading files.

Make sure you add the GIOF_LOADPREFS flag to the GioInfo() function
return value, otherwise the user will not be able to select the
"Prefs" button in the loaders list.

GioCleanUp [V1.2]
=================

NOTE [1.2a] - In V1.2 this was documented but not actually
implemented! It is now....

In previous versions, it was not safe to allocate memory or
resources inside GioExamine() without closing them down again and, if
necessary, reallocating them inside GioRead(). This was because
the memory allocation asked for by GioExamine() could fail and
GioRead() would never be called.

Now, if the GIOF_EXTENDED flag is set, and for any reason
GioExamine() is called but GioRead() is not called, GioCleanUp()
will be called instead allowing you to deallocate resources.

A typical use, to avoid repeating code, would be (in pseudocode...)

GioExamine()
{
    if(file_is_right_type)
    {
        SetUpGioDataParameters();
        AllocateMyResources();
    }
    else
        return(GIO_WRONGTYPE);
}

GioRead()
{
    ReadAndDecodeFile();
    GioCleanUp(); // deallocate resources
}

GioCleanUp()
{
    DeallocateMyResources();
}

*** NOTE!!! Do not use this function if you can otherwise avoid it. ***

.GIO files written using GioCleanUp() will *NOT* work on old (V1.0/1.1/1.1a)
versions of Photogenics, as they do not call GioCleanUp()

GioAbout() [V1.2]
=================
This routine (which is located in the assembler source module provided)
is called if the GIOF_EXTENDED flag is set and the About button is
clicked in either the loaders or savers lists in Photogenics.
Normally, this would display a requester showing information
on the .GIO file (version number, copyright text, author, etc.),
however there is no reason why you could not use any custom code
of your own for 'fancy' About requesters.

GioStartup() [NOT YET IMPLEMENTED]
==================================
GioShutDown()
===================================
These two functions are reserved for future versions and should
be left void currently. They are primarily intended for Animation loaders.

(Actually, GioShutDown() is implemented, but it's use may change from the current implementation
so we don't want to document it just yet...)


How the system works:
=====================

If you have either of the GIOF_LOADER flags set, then your
loader will appear in the "Loaders" window. On selecting this
loader it will open the GIO file and call GioExamine.

The full procedure inside Photogenics is:

flags = GioInfo();         // get flags

if(flags & GIOF_LOADFILE)  // if it needs a filename
{
   giodata->Filename = <call ASL requester to get filename>;

   if(!(flags & GIOF_NOFILEOPEN)) // by default open file..
   {
      giodata->Filehandle = Open(filename,MODE_READ);
      Read(giodata->Filehandle,&giodata->Data,64);  // read first 64-bytes
   }
}

   if(GioExamine(giodata)) goto err;            // error exit

   buff = AllocateNew24BitBuffer(giodata->Width,giodata->Height)

   if(GioRead(giodata)) goto err;               // error exit

   // After this call giodata->Depth *must* be set. Most of
   // the time it will be set in GioExamine()

   <now photogenics will covert the buffer from indexed and/or planar
    to chunky 24-bit>

/*EXIT routine here..*/

Universal load
==============
If the GioExamine() field returns WRONGTYPE it will choose the next
type from the list that fits both _LOADFILE = TRUE and _NOID = FALSE
and attempt the GioExamine() again. Note that the file is
still only opened once and the 64-bytes of data are reused.

Because of this it is essential that giodata->Data and
giodata->Filehandle are *NEVER* written to or trashed by your loader
(even if you have GIOF_NOFILEOPEN set and are not expecting them
to be used)

And always try and test the 64-bytes of header first. If you can
tell that the filetype is NOT the one you're after, quit out
as soon as you can from GioExamine() without reading any more data from the file.

The universal loader will be called automatically by "Open..." and
could always work (if the loader you select fails it automatically
tries to find a correct one).

Unlike some other image processing packages, 3rd party loaders can work
with the universal load system without alteration to our universal
loading code.

Don't build your own requesters unless you have to!
===================================================
There are *many* pre-built requsters (for input of strings, values,
new image dimensions, etc, etc, etc,) built into the photogenics
pgs.library. These provide a simple and quick way to build up
loaders.

All the reqesters are scalable and font sensitive. You do not
have to worry about what configuration the user is running when using
them.

Of course, you do not have to use these, you can use your own code or
another library (GadTools, Triton, etc, etc,), but the
main advantage of using our requesters is that if (when) in the
future we update our user interface and make it look nicer (with
better gadgets, etc.) your code will automatically take advantage
of the new features. It also makes your code smaller and reduces the
reliance on bulky and slow third party libraries.

These have been written for you to use - please use them! See pgs.doc
for information on all the current requester types.

ARexx...
--------

Since Photogenics 2 can pass you parameters from Arexx, it's probably a good idea for
you to check for them and deal with them.

The bmp.gio example doesn't have any arexx parameters, but check the balance.efx code
(in the effects drawer) for example of how to deal with arexx.

More information is provided in the efx.txt file. Using Arexx with gios is identical to using
them with effects.