Re: [AD] Renamed API second draft

[Sven Sandberg <svsa1977@xxxxxxxxxx>]

Bob wrote:
> No, there's no such thing as a compiled or rle sprite which you can
> write to or rotate *now* - this doesn't exclude the fact that these
> operations can be done.

Yes it does, practically. A compiled sprite is like a hard-coded program
with semantics like:

   putpixel(x+0,y+0,37);
   putpixel(x+1,y+0,23);
   putpixel(x+2,y+0,59);
   ...
   putpixel(x+37,y+67,97);

One thing that make them fast is that they don't need to check which
pixels are transparent -- they just don't have any operation that draws
the transparent pixels. Now say we want to draw to such a bitmap. First
we must find which place to draw at. This means we must do a linear
search from the beginning. If we are lucky, we find the position where
this pixel is, then we can draw to it, so it has expected average time
proportional to w*h. If we are unlucky, however, the pixel to which we
draw was transparent, so we must insert the new pixel at the appropriate
position. This involves reallocating memory, then moving all the
following pixels to the right, so it is extremely slow. It is the same
situation for RLE sprites: because of the encoding, you have to scan
them linearly, then possibly reallocate and move the rest of the sprite.

This can't be done in any other way, and why would you want to do it
anyway? Compiled sprites and rle sprites are good for exactly one thing:
drawing masked. In general, if you want an object which can do operation
A, then you should choose an appropriate datatype which naturally
supports doing operation A. If you choose a datatype where it is
incredibly hard to do operation A, then this is a mistake and you should
change datatype rather than try to implement something that can't be
implemented in a useful way.

For the same reason, there is no point in rotating rle or compiled
sprites because they are bad datatypes to implement rotation on (because
a rotation routine needs to read pixels from random positions in the
image, which is not supported by the datatypes compiled sprite and rle
sprite). Instead you should choose BITMAPs, which is a datatype that
supports rotation much more naturally.

So, in short, a bitmap is a datatype representing a picture which has
the operations putpixel() and getpixel() which run quickly (in constant
time). An rle sprite is a datatype representing a read-only picture
which you can draw masked or translucently masked, with or without
clipping. A compiled sprite is a datatype representing a read-only
picture which you can only draw masked. This is why I think they should
stay as separate types.

Of course, in some cases it may be useful to represent a
non-clipped-masked-blit-only picture as a BITMAP or RLE rather than a
compiled sprite. In that case the most logical thing in my opinion is
not to pretend that the restricted datatype is more generic than it is
(by making compiled sprites be special BITMAPs), but rather to pretend
that the generic datatype is more restricted than it really is (by
allowing BITMAPs to be special compiled sprites, or by inventing a new
datatype which has the same semantics as compiled sprites, like in the
mini-API I gave you).

(If you don't know java, then you can safely ignore the coming paragraph
:-) The situation is like in java if CompiledSprite is the parent class
of RleSprite (which adds the method draw_translucently()), which is the
parent class of Bitmap (which adds all sorts of methods for e.g. drawing
and rotating). You can't cast an instance of CompiledSprite to an
RleSprite or a Bitmap because that would allow you to e.g. draw a circle
onto a CompiledSprite, but there is no such method in the class
CompiledSprite. However, it is still possible to cast an instance of
class Bitmap to a CompiledSprite, because it only hides operations.

This is why I think an API like the one I suggested in my previous email
is better. Whether or not that should be a part of Allegro is a
completely different issue. I would personally think that it's
unnecessary because it's trivial to implement, but it may be worth
discussing. Another possibility could be to make COMPILED_SPRITEs able
to be represented internally as an RLE or a BITMAP (i.e. add the
functions create_bitmap_compiled_sprite(), create_rle_compiled_sprite(),
then make draw_compiled_sprite() be aware of this).

> The point is that with a merged API, we reduce the number of functions
> (good for DLL), we allow users to easily switch in between bitmap
> types (for free), we allow support of various different types of
> bitmaps which may not even be invented yet, we keep a consistent API,
> and it requires minimal effort on our part. There'll be more to add in
> the documentation than in the code.

Are you talking about adding the API I described to Allegro or about
making compiled and rle sprites be special BITMAPs? In the first case, I
don't see how any of the advantages you describe would be different if
it's in an add-on (except for the "minimal effort on our part", which is
even more minimal as an add-on :-). In the second case, see Long
Explanation above for why I still don't think this is a good idea.

-- 
Sven Sandberg   svsa1977@xxxxxxxxxx   home.student.uu.se/svsa1977