Re: [AD] allegro 5 text routines and length parameter

[Andrei Ellman <ae-a-alleg@xxxxxxxxxx>]

Doug Eleveld wrote:
> From: Elias Pschernig <elias@xxxxxxxxxx...> - 2008-03-10 11:43
> On Mon, 2008-03-10 at 04:30 -0700, Doug Eleveld wrote:
> > > Hi everyone,
> > >
> > > I just downloaded 4.9.2 to try to get an idea about
> > > the Allegro 5 text output API. What I noticed is
> that
> > > they expect a zero terminated string. This can be
> > > awkward in some cases and most similar libraries
> use a
> > > char* with an int length, where a length of -1
> means
> > > to expect a zero-terminated string.
> > >
> > > Are there any plans to have a string length
> parameter
> > > in the Allegro 5 API? Or should I try to change it
> > > myself and submit a patch? 
> > >
> > > best regards,
> > Can you give an example where this is a problem and
> > the int length is an
> > advantage?
> >
> > Anyway, I think we did not decide yet what to do
> > with the string API.
> > Like, do we want to prefix the A4 string API with
> > al_ and just use it in
> > A5 1:1?
>
> Most text drawing APIs seem to have a length parameter
> (X11, GDI) so I assume its generally considered worth
> the effort.
>
> I noticed that length parameter is useful for
> character or word-wrapping or even trying to nicely
> handle newlines.  With the current API I have to make
> a copy of the text (or the pieces) and make sure all
> the pieces are null terminated.  Its certainly doable
> with the current API but leads to awkward code to do a
> relatively simple thing.

I agree. Another use for using a 'length' paramater is if the string is 
contained in a raw data-stream that uses an alternative means of 
terminating a string (eg. length-string instead of string-0x00), the 
string can be used as it is without having to ustrncpy() to a temporary 
buffer and null-terminate it. An example is Karaoke-lyrics embedded in a 
MIDI-track datastructure. However, if the data-stream is using a 
different UNICODE-encoding format than the app, the programmer would 
would need to change format to read the string properly.

Here are some suggestions for improving Allegro's text-printing functions.

+ As mentioned above, there should be versions of textout/textprintf 
that take an extra 'length' paramater (length is in characters - not 
bytes). In order to be consistent with the standard library, there will 
be two sets of functions. One that does not take a length paramater 
(like what we have now), and one that does (textnout/textnprintf).
+ The text-output functions return the length in pixels of the printed 
string. This is useful for things like dirty-rectangles or if you just 
want to draw a rectangle round the text you've just printed and need to 
know the dimensions. As for the number outputted characters, the 
printf-format placeholder '%n' returns the number of characters printed 
so far (for textout, just use ustrlen()).
+ A 'char_length()' function that returns the length in pixels of a 
given character. At the moment, the way to do this without #including 
"aintern.h" is to copy the character to a NULL-terminated buffer and use 
text_length() on the resulting string. You can also do this the 
hacky-way by #including "aintern.h" and using the font's 
FONT_VTABLE::char_length() method.
+ A function to get the width in pixels of the longest glyph in the 
font. For large fonts that contain a large selection of the UNICODE 
character-set, it could take a while, so the user may want to call this 
rather than being called automatically whenever a FONT is initialised.
+ Escape-sequences in the text-strings for doing things like 
change-colour, italics, bold, inverse-video, etc. OpenLayer already 
implements something similar, so the escape-sequences could be made 
compatible with OpenLayer's.
+ Multi-line versions of the text-printing functions where you pass in 
the maximum line-length in pixels (or maybe even characters?). If the 
text is longer than the line-length, the text continues on the next 
line. The Allegro GUI already implements something similar.
+ Ability to vary the horizontal spacing (in pixels) between characters. 
This should also support negative spacing so that characters can 
partially overlap. This is useful if creating a font with an outline and 
you only want to use single-coloured fonts. The outline would require a 
different ammount of spacing than the regular characters. In the 
multi-line text-printing functions, vertical-spacing would also be needed.

I have already written some code that does a multi-line version of 
textout() that I've described above. It uses the existing Allegro API 
(and uses the 'char_length()' of the FONT's FONT_VTABLE directly). The 
code could be greatly simplified if some of the above suggestions were 
implemented. The code can be found at 
http://www.allegro.cc/forums/thread/581296/581382#target


AE.