This documentation is extracted from the GGI ML
(date 2002-02-02, subject: "Re: does this look acceptable" by Andreas Beck)


> > I'd like it better if one could display multiple cursors at the same
> > time.
> This is something that could be added.

Did LibBSE compile for you ? The demo game in there should show how useful
it is to have multiple cursors/sprites supported :-).

> > For the same reason (emulated sprites) I'd recommend to have a
> > "Hideifemulated" Function which gets used for hiding emulated cursors
> > while drawing.
> Could you expand on this.  HOw would it work?  I thought about this and
> sort of just forgot about it because it was interfering w/ progress.

If you "emulate" a cursor (and I think this should be possible, as
according to the GGI philosophy, we should enable to user to program
generically, no matter if the hardware supports the cursor type he wants),
you got to draw it over the screen contents.

On some targets it can be overlayed after blitting out a background buffer
or similar, in which case it is no problem, but the common case is that
you really got to manipulate the main screen content.

Now this is usually done by saving the background, drawing the sprite and
later restoring the background when the sprite moves.

Now if you draw while the sprite is shown, and draw thorugh the sprite,
the change will be undone when the sprite moves. Thus emulated sprites
that reside on the main screen have to be hidden while you draw.
Unfortunately this makes them flicker a bit.

For this reason it makes sense to hide a cursor only when it is emulated.
Thus hardware cursors do not flicker while drawing, software ones do.

Another thing: For user convenience it is important to count Hide/Show
requests. Subroutines that draw something or temporarily want to disable
the cursor will be a PITA otherwise. Behaviour should be to have a
hidecount variable and only show when it is 0.

Yet another thing: If you have multiple emusprites, you have to hide them
in the right order, as drawing/hiding an emusprite is a drwaing operation
... LiBBSE makes quite some show of doing that right ...

Thus I propose the following architecture:

[LibOverlay]  [LibBlit]
       \        /
        [LibBSE]

With LibOverlay containing access to hardware-sprites and other Overlay
stuff like YUV-Viewports etc. and LibBlit giving access to Blitting
operations which can be used for emulated sprites, both done as
extensions.

The API should be somewhat uniform to allow the "normal" (non-extension)
Lib LibBSE to easily dispatch an abstract "Object", which might be a
Sprite, a Bob or an EmuSprite to the underlying subsystems.

I think that is what helps users the most. Given few targets now allow
hardware cursors or can easily be hacked to do so, I'd recommend to have
that possibility to do software-fallback.

Moreover both extension libs have their individual uses standalone and
they are technically very different, which is why they should be split and
then glued again with LibBSE for user convenience.

> > For performance reasons, I'd recommend to bind cursors to visuals, as an
> > optimized representation can then be stored to make blitting quicker.
> A = ggiLoadCursor( V, A-data) ; B = ggiLoadCursor( V,  B-data)
> C = ggiLoadCursor( V, C-data) ; ggiSetCursor(V, B);
> Of course if you have visual  W,
> ggiSetCursor(W, B);'
> makes no sense because B was loaded into V  not W.  
> This would return an error. Is this OK?

Right.

> THIS IS WHAT I AM TALKING ABOUT
>      V
> > ggibse_t        ggiBseAllocate  (ggi_visual_t vis, int width, int height,

> Here you associate a handle with a visual.  Would it make sense to use
> this handle with another visual?  I don't think so.

Right, it doesn't make sense, as you got to optimize it to the visual in
question. LibBSE AFAIK checks for that association and throws errors if it
is violated.

> I'm totally confused. Of course, I don't know *anything* about h/w
> cursor implementations, but I would assume that the cursor's pixel
> layout is the same as that of the corresponding visual.

For hardware cursors it usually isn't. For software ones it is. Thus I
propose to specify the cursor in a generic format and let the LibOvl say,
if the hardware can do it, and if it can't, you just fall back to using
LibBlit and do it in Software. Of course for convenience, I'd place a
layer in between that handles this transparently for me.

> Having a palette for the cursor which needs to be translated

Many HW cursors have their own palette.

