[ft-devel] Re: Some public APIs using FT_Int/FT_UInt should be improved in future

[Werner LEMBERG]

> Just I've finished the outline to clear implicit cast warnings on
> LP32 and LP64 platforms by AtariST/PureC and Mac OS X/gcc for ppc64.

Great!  Thanks a lot.  And your observations below show that it wasn't
wasted time.

> A) Some 32bit (or more, in future extension?) flags are
>    interchanged by FT_UInt.
>
>    Example: FT_Get_Advance(), FT_Get_Advance() receive flags by
>    FT_UInt type, but FT_ADVANCE_FLAG_FAST_ONLY (=0x20000000UL) etc
>    cannot be passed by FT_UInt on 16bit system.
>
>    Although the extension from FT_UInt to portable 32bit integer
>    makes 16bit systems troubled, I think it should be extended.  To
>    keep ILP32/LP64 systems unchanged, using FT_UInt32 would be most
>    appropriate.

Please use FT_Long for FT_Get_Advance and FT_Get_Advances since they
are new in version 2.3.8, so no compatibility problems can occur.  Are
there other functions which have this problem?

>    FT_Bitmap_Embolden() receives the strength of embolding
>    by FT_Pos-typed variables: [...]
>
>           align = ( bitmap->width + xstr + 3 ) / 4;
>    [...]
>
>         error = FT_Bitmap_Convert( library, bitmap, &tmp, align );
>
>
>     However, I think it's not reasonable to pass such a large
>     value greater than 16bit range.

Indeed.  As the documentation describes, common values are 1, 2, or 4,
which is far away from the 16-bit limit.

>     I want to insert the warnings for overflow cases and keep the
>     APIs as they are, and discuss this issue again in future when
>     incompatible API update is scheduled.

What about adding to the docs that `alignment' must be < 65536?  Then
we can easily exit with FT_Err_Invalid_Argument.

>    Most public APIs, FT_Load_Glyph(), FT_Get_Glyph_Name() etc
>    receive the glyph index by FT_UInt.  On 16bit system, using
>    FT_UInt restricts the glyph index to 16bit, although the number
>    of glyphs (FT_Long) is still 32bit.  I think using FT_ULong (or
>    FT_Long) would be more consistent.

Well...

>    But, BDF/PCF are only font formats that can bring 32bit glyph
>    index to FT2, so it is questionable if the extension of glyph
>    index in public APIs is so worthful that we decide to break the
>    API compatibility on 16bit platform.

I believe that PS fonts (e.g., Type 1) can also have more than 65536
glyphs.  Anyway, I vote again for restricting the maximum value of the
glyph index to 65535.  In case someone really needs access to higher
glyph indices, we can easily add an FT_Load_Glyph32() function.

> D) Some bitmap-image related properties mix int and long types.
>
>    Example: pfr_slot_load_bitmap() versus FT_GlyphSlot
>
>    FT_GlyphSlot has 2 integer parameters:
>
>                       FT_Int  bitmap_left;
>                       FT_Int  bitmap_top;
>
>    FT_Bitmap members are similar, but more directly (not FT_Int but
>    int)
>
>                       int  rows;
>                       int  width;
>                       int  pitch;

The use of `int' is intentional since it should be able to cooperate
with the stand-alone `mode' of ftgrays.c.

>    But pfr_slot_load_bitmap() tries to write FT_Long values to
>    there.
>
> ???===> glyph->root.bitmap.pitch = (FT_Long)( xsize + 7 ) >> 3;
> ======> glyph->root.bitmap_left = xpos;
> ======> glyph->root.bitmap_top  = ypos + ysize;
>
>    I'm not sure why pitch is casted to FT_Long.

Looks like bugs.

>    According to PFR spec sheet, theoretically PFR can include
>    extremely high resolution bitmap upto 24bit length (16.7M pixel,
>    I don't think it's realistic), x/ypos must be typed as long (or
>    greater). This is big contrast with embedded bitmap TrueType
>    limited to 8bit length.

Again, I suggest to limit the dimensions to 65535.

>    The BDF/PCF drivers in FreeType2 restricts bounding box
>    properties to signed short, [...]
>
>    I think BDF spec sheet does not restrict these properties to
>    16bit integer, but these restrictions were introduced for
>    pragmatic simplification.  I don't think there's urgent need to
>    extend them to long (the maximum integer type which is portable
>    in ANSI-C).

I would rather go one step further and document the limitation.

>    In summary, PFR is the only implementation I could find, which
>    should store pixel size in 32bit and requests the 32bit extension
>    of FT_GlyphSlot and FT_Bitmap (it does not change anything for
>    ILP32 systems, but 16bit system would be changed).  But, it is
>    very questionable if the support of huge bitmap in PFR is
>    worthful for 16bit platforms, in comparison with breaking binary
>    compatibility with previous releases.  Breaking the compatibility
>    of public data type (not only function interface) would be a
>    remarkable impact.  Thus, I want to keep the public types as they
>    are, and I want to insert the warnings for the overflow cases.

I fully agree with your analysis.  Guess what I recommend :-)

> About the discussion to extend FT_UInt to FT_UInt32 (or FT_ULong)
> for case B, C and D, I want to postpone them until the day when FT2
> or FT3 define new API set including incompatible changes.

No need to postpone, I think.


    Werner