Re: some more issues with the new API

[Just van Rossum]

At 2:14 PM +0100 16-03-2000, David Turner wrote:
>I believe that my opinion of the subject is biased by the fact that
>the first text service I developed on top of FreeType 2 didn't need
>anything more than the current API. It provided all the normal text
>services (as the one you describe below), without ever needing
>higher-level classes.

I'm not even talking about higher level classes, however my point is
largely this: part of the functionality (possibly expressed by "ordinary" C
functions) you wrote for that text service could be reusable, and could
therefore be part of FreeType (or FreeText if you will ;-)

>Of course, it was developed for FT2, and FT2 was developed for it,
>so there was tight integration, and one of the design requirements
>was that the code had to be small, and use few memory, which it did..

And that's one of FT's major assets: it's lean and mean! I just wished more
of your text services would've flown back into FT2...

>However, your remarks make it clear that the API might be a bit too
>low level for most users, and needs a revamp..

Or just write a layer on top of it...

>It all boils down to what kind of service you want to provide. For now,
>I'll stick to "font service" for FreeType 2.

But what people need most is a "text service"...

>> "Not always"? When is it? The semantics are blurry, to say the least.
>>
>Yes, I'm sorry if this blurry. I'm still convinced that these details
>should not be exposed to a high-level interface. We'll have to move
>these fuctions to internal header files..

But they're needed to be able to create a higher level API, so you can't
hide that stuff completely..

[ thread-safe drivers ]
>I have not all details in mind, but I believe it all related to the amount
>of sharing between objects and drivers. Thread-safety meant either duplicate
>most data or make the design more complex. And the first option wasn't really
>welcome..

But of course data duplication is not an option... My point is that if you
decouple all state from the face object, it wouldn't neccesarily result in
a more complex (or less efficient) design, except you need to explicitly
pass all state around. But maybe that's exactly what you don't like...

>Now, for the serious stuff, how can we make the FT2 API a bit more abstract.
>
>Should we introduce the FT_Glyph / FT_GlyphBitmap / FT_GlyphOutline types
>(moving FT_GlyphSlot under the hood) ?
>
>We can also specify a transform as in FT_Set_Transform in order to generate
>transformed outlines/bitmaps directly ?
>
>I still don't think that users should see the FT_Size and FT_GlyphSlot
>objects. These concepts are deeply rooted to the way font files are
>structured and how font drivers are able to "sub-class" the root types..

Here's a stab at a higher level API, using Python syntax:

# -----

bitmap = some_function_that_creates_a_bitmap(...)
face = freetype.OpenFace("fontname.pfb")

position = face.NewPosition(ppem, (x, y), transformation, flags)

for char in "A string":
    glyphID = face.getGlyphID(char)
    face.renderGlyph(glyphID, position, loadFlags, bitmap)

# -----

I introduced a new object, possibly called FT_Position which holds the
following state:
- ppem/pointSize/resolution
- a transformation, possibly NULL to indicate the identity transformation
- an offset, the "current point"
- hint flags??
(possibly it holds a reference to the face object)

I can imagine that face.renderGlyph() updates the current position
according to the glyph's metrics, but maybe it's better to let clients do
this explicitly:

for char in "A string":
    glyphID = face.getGlyphID(char)
    face.renderGlyph(glyphID, position, loadFlags, bitmap)
    position.move(face.getGlyphMetrics(glyphID, ppem))  # <--

This is all pretty much off the top of my head, so I'm quite possibly
overlooking some things... Let me try and translate my ideas to a C example
(skipping error handling to keep it legible...):


{
  FT_Face      face;
  FT_Position  position;
  int          glyphID;
  int          charCode = 'A';
  FT_Bitmap    bitmap;
  FT_Metrics   metrics;

  Some_Function_That_Creates_A_Bitmap( dimensions, &bitmap );

  FT_Open_Face( library, "Fontname.ttf", &face );

  /* not sure what 'flags' may be... */
  FT_Set_Position( face, ppem, offset, transformation, flags, &position );

  glyphID = FT_Get_GlyphID( face, charCode );

  FT_Render_Glyph( glyphID, &position, loadFlags, bitmap );

  /* the next two lines may be implicitly performed by FT_Render_Glyph */
  FT_Get_Glyph_Metrics( glyphID, ppem, &metrics );
  FT_Position_Move( &position, &metrics );

  /* clean up */
  FT_Done_Face( face );
}


Just