Amiga ISO Collection/AmigaUtilCD1.iso/GFX/Misc/OTT-PHT3.DMS/in.adf/devdocs/gio/gio.doc

Text File | 1994-11-21 | 12.7 KB | 371 lines

Programming information for .GIO files
======================================

Copyright © Almathera Systems Ltd 1994. 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 or Keith Smith on (UK) 0181 687 0040
during office hours, or email to:

[e-mail]

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 (21/11/94)
==============================================

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, fractal creation, 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.) although all
the examples provided use SAS V6.50 or higher as library
creation with this is simple using the libinitr link code.

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.

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)
##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!

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 fractal creators/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)+3*x;
    *byteptr++ = red;
    *byteptr++ = green;
    *byteptr   = blue;
    ReleaseLine(giodata,y);

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 saving 24-bit data. 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.

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)

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 other image processing packages, 3rd party loaders work
can work with the universal load system without alteration to our
universal loading code.