From: Andrew Apted <ajapted@netspace.net.au>
  To  : ggi-develop@eskimo.com
  Date: Thu, 6 Aug 1998 11:28:04 +1000

Re: ggiGetPixelFormat and proposed new DirectBuffer scheme

Marcus writes:

>  > First question, how does GGI_PF_REVERSE_ENDIAN relate to the masks ?
>  > Does it mean that masks don't change (e.g. r5g5b5), and the program has
>  > to byte swap *after* encoding a pixel using the masks ?
>  
>  Yes, I think this makes most sense.
>  Having masks like:
>  ggbbbbb0 rrrrrggg
>  would imply that gg in the left byte are the high-bits, which
>  is not correct. Thus we have:
>  rrrrrggg ggbbbbb0
>  and GGI_PF_REVERSE_ENDIAN tells us that we need to swap the
>  bytes.

Right.

>  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).

>  Also, I suggest we make GGI_PF_HIGHBIT_LEFT the default and
>  remove that flag. Agreed?

Agreed.

>  > Second question, what about 1..7 bit modes ?  For example, on a 1 bit
>  > mode the above should have clut_mask == 0x01.  I think that's OK, but it
>  > does imply that ggiGetXXX/ggiPutXXX don't take packed data (e.g. 8
>  > pixels packed in each byte) but *unpacked* data (one pixel per byte).
>  > 
>  > I prefer the unpacked case, it is so much easier to program for, since
>  > you don't have to worry about packing the data (with LSBit vs MSBit).
>  > The disadvantage is ggiPutXXX can't resort to memcpy _when the data is
>  > aligned_.  I'm not worried about this, applications can always access
>  > the framebuffer directly to get a speed boost.
>  > (I guess that 1 bit modes under X would be slower too -- but IMHO the
>  > nicer interface for all depths < 8 is more important than the speed of
>  > 1 bit modes).
>  
>  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).

>  > We're going to need blBitPlanarBuffer and blInterleavedPlanarBuffer soon
>  > (when running LibGGI on linux/m68k).  Just something to keep in mind.
>  
>  Yep. DirectBuffer should support planar modes out of the box.

Yes, for sure.

>  For Get/Put buffers I think it makes most sense to use chunky
>  pixels even if the HW is planar, as it will allow applications
>  to run everywhere without needing to now anything about planar
>  modes. 

Definitely.  It would be the height of silliness for an application to
have to convert a little 11x11 image into 8 little planes :-).

>  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).

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) ?

>  > 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.

Cheers,
_____________________________________________  ____
                                               \  /
  Andrew Apted   <andrew@ggi-project.org>       \/