From: Marcus Sundberg <e94_msu@e.kth.se>
  To  : ggi-develop@eskimo.com
  Date: Thu, 06 Aug 1998 18:37:36 +0200

Re: ggiGetPixelFormat and proposed new DirectBuffer scheme

Andrew Apted wrote:
> 
> Marcus writes:
> >  Btw, doesn't many processors have an instruction to do byte
> >  swapping? In that case I suggest we add some byte swapping
> >  macros to the API, which will use inline-assembly on supported
> >  platforms.
> 
> I guess many processors could do it with a single Rotate instruction
> (e.g. ROL.W #8,D0 on 68000 IIRC).

For 16 bit words, yes.
And it seems we might not have to use assembly - gcc compiles
x = x<<8 | x>>8; into rorw $8,x even with optimization off.
Really strange thing though is that if -O2 or higher is used it
becomes rolw $8,x :-)
Anyone who knows if rolw is really faster than rorw, or is it just
some gcc strangeness?

Anyway I suggest we add
#define GGI_BYTEREV16(x) ((x) = (x)<<8 | (x)>>8)
#define GGI_BYTEREV32(x) ((x) = ((x)<<24 | (x)>>24) | \
			(((x)<<8 & 0xff<<16) | ((x)>>8 & 0xff<<8))

to the API.
The latter could probably be optimized in assembler on some CPUs.

> >  3,5,6 and 7 bit modes should definitely be unpacked, because
> >  I've never heard of any HW that supports such modes with a packed
> >  chunky buffer. :)
> >  For the other modes I suggest we have a GGI_PF_PACKED flag that
> >  indicate that _aligned_ buffers uses packed format.
> >  After all, <8 bit modes are almost only used on old hardware
> >  where speed is always an issue.
> 
> Well we're talking get/put buffer, so instead of a GGI_PF_PACKED flag
> I think a GT_SUBSCHEME_PACKED flag would make more sense.  Applications
> that want their get/put buffers to be packed (1..7 bit modes) would set
> this bit in the graphtype when calling ggiSetMode/SetGraphMode.  [Most
> applications would be happier handling unpacked get/put].
> 
> And if packed wasn't possible (or non-standard e.g. 75316420) then it
> should be reset and applications would fallback to using unpacked
> get/put buffers.
> 
> Taking all this into account, the subschemes would now be :
> 
>     #define GT_SUBSCHEME_STANDARD         (0x80 << GT_SUBSCHEME_SHIFT)
> 
>     #define GT_SUBSCHEME_REVERSE_ENDIAN   (0x01 << GT_SUBSCHEME_SHIFT)
>     #define GT_SUBSCHEME_HIGHBIT_RIGHT    (0x02 << GT_SUBSCHEME_SHIFT)
>     #define GT_SUBSCHEME_PACKED_GETPUT    (0x04 << GT_SUBSCHEME_SHIFT)
> 
> when GT_SUBSCHEME_STANDARD is not set, then the mode is something
> unusual and encoding pixels and get/put buffers is not possible.
> (and 0 is GT_AUTO of course).

get/put buffers are always possible (as long as the display has
the notion of pixels at all ;) but you have to use
ggiMapColor/ggiUnmapPixel to encode/decode them if 
GT_SUBSCHEME_STANDARD isn't set. Maybe that's what you meant?

> >  This was my originally planned changes to structs.h:
> >
> >  --- old/include/structs.h       Thu Jul 23 09:35:59 1998
> >  +++ ./include/structs.h Tue Aug  4 16:40:14 1998
> >  @@ -77,6 +77,14 @@
> >          void *private;
> >   } ggi_extlist;
> >
> >  +/* Direct Buffer stuff */
> >  +typedef struct {
> >  +       int                     numbufs;
> >  +       ggi_directbuffer        **buffers;
> >  +
> >  +       void    *dummy[8];      /* for future expansion */
> >  +} ggi_db_internal;
> >  +
> >   /* Increment the version number every time you add
> >    * new features.
> >    */
> >  @@ -102,7 +110,12 @@
> >          struct ggi_visual_opgc      *opgc;  /* GC operations */
> >          void                        *opdummy[5];/* For future expansion */
> >
> >  -       struct ggi_info info;           /* Info on the mode */
> >  +       ggi_pixelformat *pixfmt;        /* Format of the pixels */
> >  +       ggi_db_internal *dblist;        /* List of DBs */
> >  +       ggi_flags       flags;          /* Flags */
> >  +       ggi_mode        *mode;          /* Current mode */
> >  +       int             select_fd;
> >  +
> >          int size;                       /* Size of all extensions */
> >          ggi_dlhandle_l  *extlib;        /* Dynamic libs from extensions */
> >
> >  I suggest we add:
> >         int                     numpriv;
> >         ggi_directbuffer        **privbufs;
> >  to ggi_db_internal. That way application- and internal buffers are
> >  completely separated.
> 
> OK.  Linked lists would be nicer, so that targets can take the
> direct-buffers created by generic-linear-*, and moved them from private
> to public list.  (NB: default would be private, and targets that want to
> export them could e.g. call _ggiExportDirectBuffers).

Linked lists will be slow when you have a couple of buffers and
some driverlib has to look up a property in one of the buffers.
(Perhaps it needs the write-address to put just a single pixel)

Moving buffers is non-performance critcal and can therefore be
done with:
buffers = realloc(buffers, numbufs+1);
buffers[numbufs] = privbuf[idx];
memcpy(privbuf+idx, privbuf+idx+1, numpriv-idx-1);
privbuf = realloc(privbuf, numpriv-1);

> BTW, how do you differentiate direct-buffers that correspond to frames
> (where frame_number is valid) and anything else ?  Just having
> GGI_DB_NORMAL set (and clear for the rest) ?

Something like that, yes.

> >  > Possible addition:
> >  >
> >  >         int       non_standard;       /* non standard framebuffer types */
> >  >
> >  > which would normally be 0, but would take on special values if the
> >  > framebuffer was partically strange, e.g. :
> >  >
> >  >     #define GGI_DB_NONSTD_VGA_MODEX
> >  >     #define GGI_DB_NONSTD_VGA_MODEY
> >  >     #define GGI_DB_NONSTD_HAM6
> >  >     #define GGI_DB_NONSTD_HAM8
> >  >
> >  > (though maybe this could be handled by the extension mechanism)
> >
> >  Any reason why we shouldn't simply add the above four and
> >  similiar modes to the ggi_bufferlayout enumeration ?
> 
> I know HAM6 would just have a bit-planer buffer layout, so it's more of
> a "pixel format is weird" thing.  As for the others, I wouldn't know,
> they were just hypothetical examples.

MODEX/Y is defenitely a separate buffer-layout.
And HAM6/8 is easily dealt with by adding a GGI_PF_HAM flag
to the ggi_pixelformat struct.

//Marcus
-- 
-------------------------------+------------------------------------
        Marcus Sundberg        | http://www.stacken.kth.se/~mackan/
 Royal Institute of Technology |       Phone: +46 707 295404
       Stockholm, Sweden       |      E-Mail: e94_msu@e.kth.se