summaryrefslogtreecommitdiffstats
path: root/src/3rdparty/freetype
diff options
context:
space:
mode:
Diffstat (limited to 'src/3rdparty/freetype')
-rw-r--r--src/3rdparty/freetype/README18
-rw-r--r--src/3rdparty/freetype/builds/unix/ftsystem.c4
-rw-r--r--src/3rdparty/freetype/docs/CHANGES197
-rw-r--r--src/3rdparty/freetype/docs/CUSTOMIZE2
-rw-r--r--src/3rdparty/freetype/docs/DEBUG21
-rw-r--r--src/3rdparty/freetype/docs/TODO2
-rw-r--r--src/3rdparty/freetype/include/freetype/config/ftconfig.h420
-rw-r--r--src/3rdparty/freetype/include/freetype/config/ftheader.h352
-rw-r--r--src/3rdparty/freetype/include/freetype/config/ftmodule.h12
-rw-r--r--src/3rdparty/freetype/include/freetype/config/ftoption.h1369
-rw-r--r--src/3rdparty/freetype/include/freetype/config/ftstdlib.h160
-rw-r--r--src/3rdparty/freetype/include/freetype/freetype.h6954
-rw-r--r--src/3rdparty/freetype/include/freetype/ftadvanc.h239
-rw-r--r--src/3rdparty/freetype/include/freetype/ftbbox.h129
-rw-r--r--src/3rdparty/freetype/include/freetype/ftbdf.h241
-rw-r--r--src/3rdparty/freetype/include/freetype/ftbitmap.h438
-rw-r--r--src/3rdparty/freetype/include/freetype/ftbzip2.h140
-rw-r--r--src/3rdparty/freetype/include/freetype/ftcache.h1190
-rw-r--r--src/3rdparty/freetype/include/freetype/ftchapters.h284
-rw-r--r--src/3rdparty/freetype/include/freetype/ftcid.h102
-rw-r--r--src/3rdparty/freetype/include/freetype/ftcolor.h311
-rw-r--r--src/3rdparty/freetype/include/freetype/ftdriver.h749
-rw-r--r--src/3rdparty/freetype/include/freetype/fterrdef.h101
-rw-r--r--src/3rdparty/freetype/include/freetype/fterrors.h263
-rw-r--r--src/3rdparty/freetype/include/freetype/ftfntfmt.h117
-rw-r--r--src/3rdparty/freetype/include/freetype/ftgasp.h74
-rw-r--r--src/3rdparty/freetype/include/freetype/ftglyph.h999
-rw-r--r--src/3rdparty/freetype/include/freetype/ftgxval.h490
-rw-r--r--src/3rdparty/freetype/include/freetype/ftgzip.h226
-rw-r--r--src/3rdparty/freetype/include/freetype/ftimage.h1771
-rw-r--r--src/3rdparty/freetype/include/freetype/ftincrem.h139
-rw-r--r--src/3rdparty/freetype/include/freetype/ftlcdfil.h311
-rw-r--r--src/3rdparty/freetype/include/freetype/ftlist.h421
-rw-r--r--src/3rdparty/freetype/include/freetype/ftlzw.h137
-rw-r--r--src/3rdparty/freetype/include/freetype/ftmac.h399
-rw-r--r--src/3rdparty/freetype/include/freetype/ftmm.h1103
-rw-r--r--src/3rdparty/freetype/include/freetype/ftmodapi.h946
-rw-r--r--src/3rdparty/freetype/include/freetype/ftmoderr.h191
-rw-r--r--src/3rdparty/freetype/include/freetype/ftotval.h303
-rw-r--r--src/3rdparty/freetype/include/freetype/ftoutln.h941
-rw-r--r--src/3rdparty/freetype/include/freetype/ftparams.h99
-rw-r--r--src/3rdparty/freetype/include/freetype/ftpfr.h258
-rw-r--r--src/3rdparty/freetype/include/freetype/ftrender.h214
-rw-r--r--src/3rdparty/freetype/include/freetype/ftsizes.h239
-rw-r--r--src/3rdparty/freetype/include/freetype/ftsnames.h394
-rw-r--r--src/3rdparty/freetype/include/freetype/ftstroke.h431
-rw-r--r--src/3rdparty/freetype/include/freetype/ftsynth.h38
-rw-r--r--src/3rdparty/freetype/include/freetype/ftsystem.h134
-rw-r--r--src/3rdparty/freetype/include/freetype/fttrigon.h84
-rw-r--r--src/3rdparty/freetype/include/freetype/fttypes.h851
-rw-r--r--src/3rdparty/freetype/include/freetype/ftwinfnt.h162
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/autohint.h326
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/cffotypes.h88
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/cfftypes.h95
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftcalc.h246
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftdebug.h248
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftdrv.h336
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftgloadr.h55
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/fthash.h28
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftmemory.h77
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftobjs.h1273
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftpsprop.h32
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftrfork.h305
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftserv.h669
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftstream.h106
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/fttrace.h84
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/ftvalid.h82
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/internal.h46
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/psaux.h601
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/pshints.h170
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svbdf.h48
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svcfftl.h54
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svcid.h53
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svfntfmt.h38
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svgldict.h59
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svgxval.h50
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svkern.h32
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svmetric.h62
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svmm.h150
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svotval.h32
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svpfr.h32
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svpostnm.h58
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svprop.h48
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svpscmap.h80
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svpsinfo.h57
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svsfnt.h49
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svttcmap.h94
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svtteng.h34
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svttglyf.h45
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/services/svwinfnt.h32
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/sfnt.h1094
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/t1types.h85
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/tttypes.h2010
-rw-r--r--src/3rdparty/freetype/include/freetype/internal/wofftypes.h112
-rw-r--r--src/3rdparty/freetype/include/freetype/t1tables.h616
-rw-r--r--src/3rdparty/freetype/include/freetype/ttnameid.h138
-rw-r--r--src/3rdparty/freetype/include/freetype/tttables.h976
-rw-r--r--src/3rdparty/freetype/include/freetype/tttags.h34
-rw-r--r--src/3rdparty/freetype/include/ft2build.h64
-rw-r--r--src/3rdparty/freetype/qt_attribution.json2
-rw-r--r--src/3rdparty/freetype/src/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/autofit/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/autofit/afangles.c52
-rw-r--r--src/3rdparty/freetype/src/autofit/afangles.h6
-rw-r--r--src/3rdparty/freetype/src/autofit/afblue.c39
-rw-r--r--src/3rdparty/freetype/src/autofit/afblue.cin32
-rw-r--r--src/3rdparty/freetype/src/autofit/afblue.dat28
-rw-r--r--src/3rdparty/freetype/src/autofit/afblue.h171
-rw-r--r--src/3rdparty/freetype/src/autofit/afblue.hin32
-rw-r--r--src/3rdparty/freetype/src/autofit/afcjk.c195
-rw-r--r--src/3rdparty/freetype/src/autofit/afcjk.h38
-rw-r--r--src/3rdparty/freetype/src/autofit/afcover.h32
-rw-r--r--src/3rdparty/freetype/src/autofit/afdummy.c42
-rw-r--r--src/3rdparty/freetype/src/autofit/afdummy.h34
-rw-r--r--src/3rdparty/freetype/src/autofit/aferrors.h48
-rw-r--r--src/3rdparty/freetype/src/autofit/afglobal.c98
-rw-r--r--src/3rdparty/freetype/src/autofit/afglobal.h46
-rw-r--r--src/3rdparty/freetype/src/autofit/afhints.c181
-rw-r--r--src/3rdparty/freetype/src/autofit/afhints.h238
-rw-r--r--src/3rdparty/freetype/src/autofit/afindic.c32
-rw-r--r--src/3rdparty/freetype/src/autofit/afindic.h34
-rw-r--r--src/3rdparty/freetype/src/autofit/aflatin.c304
-rw-r--r--src/3rdparty/freetype/src/autofit/aflatin.h44
-rw-r--r--src/3rdparty/freetype/src/autofit/aflatin2.c147
-rw-r--r--src/3rdparty/freetype/src/autofit/aflatin2.h34
-rw-r--r--src/3rdparty/freetype/src/autofit/afloader.c175
-rw-r--r--src/3rdparty/freetype/src/autofit/afloader.h42
-rw-r--r--src/3rdparty/freetype/src/autofit/afmodule.c88
-rw-r--r--src/3rdparty/freetype/src/autofit/afmodule.h36
-rw-r--r--src/3rdparty/freetype/src/autofit/afranges.c47
-rw-r--r--src/3rdparty/freetype/src/autofit/afranges.h32
-rw-r--r--src/3rdparty/freetype/src/autofit/afscript.h38
-rw-r--r--src/3rdparty/freetype/src/autofit/afshaper.c61
-rw-r--r--src/3rdparty/freetype/src/autofit/afshaper.h32
-rw-r--r--src/3rdparty/freetype/src/autofit/afstyles.h39
-rw-r--r--src/3rdparty/freetype/src/autofit/aftypes.h252
-rw-r--r--src/3rdparty/freetype/src/autofit/afwarp.c54
-rw-r--r--src/3rdparty/freetype/src/autofit/afwarp.h36
-rw-r--r--src/3rdparty/freetype/src/autofit/afwrtsys.h32
-rw-r--r--src/3rdparty/freetype/src/autofit/autofit.c33
-rw-r--r--src/3rdparty/freetype/src/autofit/module.mk2
-rw-r--r--src/3rdparty/freetype/src/autofit/rules.mk3
-rw-r--r--src/3rdparty/freetype/src/base/Jamfile7
-rw-r--r--src/3rdparty/freetype/src/base/ftadvanc.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftbase.c36
-rw-r--r--src/3rdparty/freetype/src/base/ftbase.h32
-rw-r--r--src/3rdparty/freetype/src/base/ftbbox.c368
-rw-r--r--src/3rdparty/freetype/src/base/ftbdf.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftbitmap.c376
-rw-r--r--src/3rdparty/freetype/src/base/ftcalc.c194
-rw-r--r--src/3rdparty/freetype/src/base/ftcid.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftcolor.c157
-rw-r--r--src/3rdparty/freetype/src/base/ftdbgmem.c60
-rw-r--r--src/3rdparty/freetype/src/base/ftdebug.c179
-rw-r--r--src/3rdparty/freetype/src/base/fterrors.c46
-rw-r--r--src/3rdparty/freetype/src/base/ftfntfmt.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftfstype.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftgasp.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftgloadr.c134
-rw-r--r--src/3rdparty/freetype/src/base/ftglyph.c141
-rw-r--r--src/3rdparty/freetype/src/base/ftgxval.c50
-rw-r--r--src/3rdparty/freetype/src/base/fthash.c28
-rw-r--r--src/3rdparty/freetype/src/base/ftinit.c217
-rw-r--r--src/3rdparty/freetype/src/base/ftlcdfil.c127
-rw-r--r--src/3rdparty/freetype/src/base/ftmac.c106
-rw-r--r--src/3rdparty/freetype/src/base/ftmm.c107
-rw-r--r--src/3rdparty/freetype/src/base/ftobjs.c589
-rw-r--r--src/3rdparty/freetype/src/base/ftotval.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftoutln.c148
-rw-r--r--src/3rdparty/freetype/src/base/ftpatent.c34
-rw-r--r--src/3rdparty/freetype/src/base/ftpfr.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftpsprop.c48
-rw-r--r--src/3rdparty/freetype/src/base/ftrfork.c72
-rw-r--r--src/3rdparty/freetype/src/base/ftsnames.c78
-rw-r--r--src/3rdparty/freetype/src/base/ftstream.c58
-rw-r--r--src/3rdparty/freetype/src/base/ftstroke.c120
-rw-r--r--src/3rdparty/freetype/src/base/ftsynth.c46
-rw-r--r--src/3rdparty/freetype/src/base/ftsystem.c281
-rw-r--r--src/3rdparty/freetype/src/base/fttrigon.c76
-rw-r--r--src/3rdparty/freetype/src/base/fttype1.c32
-rw-r--r--src/3rdparty/freetype/src/base/ftutil.c54
-rw-r--r--src/3rdparty/freetype/src/base/ftver.rc10
-rw-r--r--src/3rdparty/freetype/src/base/ftwinfnt.c32
-rw-r--r--src/3rdparty/freetype/src/base/rules.mk11
-rw-r--r--src/3rdparty/freetype/src/bdf/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/bdf/bdf.h82
-rw-r--r--src/3rdparty/freetype/src/bdf/bdfdrivr.c69
-rw-r--r--src/3rdparty/freetype/src/bdf/bdfdrivr.h9
-rw-r--r--src/3rdparty/freetype/src/bdf/bdferror.h10
-rw-r--r--src/3rdparty/freetype/src/bdf/bdflib.c411
-rw-r--r--src/3rdparty/freetype/src/bzip2/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/bzip2/ftbzip2.c52
-rw-r--r--src/3rdparty/freetype/src/bzip2/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/cache/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/cache/ftcache.c32
-rw-r--r--src/3rdparty/freetype/src/cache/ftcbasic.c36
-rw-r--r--src/3rdparty/freetype/src/cache/ftccache.c34
-rw-r--r--src/3rdparty/freetype/src/cache/ftccache.h64
-rw-r--r--src/3rdparty/freetype/src/cache/ftccback.h32
-rw-r--r--src/3rdparty/freetype/src/cache/ftccmap.c62
-rw-r--r--src/3rdparty/freetype/src/cache/ftcerror.h48
-rw-r--r--src/3rdparty/freetype/src/cache/ftcglyph.c32
-rw-r--r--src/3rdparty/freetype/src/cache/ftcglyph.h166
-rw-r--r--src/3rdparty/freetype/src/cache/ftcimage.c32
-rw-r--r--src/3rdparty/freetype/src/cache/ftcimage.h50
-rw-r--r--src/3rdparty/freetype/src/cache/ftcmanag.c38
-rw-r--r--src/3rdparty/freetype/src/cache/ftcmanag.h143
-rw-r--r--src/3rdparty/freetype/src/cache/ftcmru.c32
-rw-r--r--src/3rdparty/freetype/src/cache/ftcmru.h80
-rw-r--r--src/3rdparty/freetype/src/cache/ftcsbits.c92
-rw-r--r--src/3rdparty/freetype/src/cache/ftcsbits.h32
-rw-r--r--src/3rdparty/freetype/src/cache/rules.mk4
-rw-r--r--src/3rdparty/freetype/src/cff/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/cff/cff.c33
-rw-r--r--src/3rdparty/freetype/src/cff/cffcmap.c35
-rw-r--r--src/3rdparty/freetype/src/cff/cffcmap.h32
-rw-r--r--src/3rdparty/freetype/src/cff/cffdrivr.c326
-rw-r--r--src/3rdparty/freetype/src/cff/cffdrivr.h34
-rw-r--r--src/3rdparty/freetype/src/cff/cfferrs.h46
-rw-r--r--src/3rdparty/freetype/src/cff/cffgload.c64
-rw-r--r--src/3rdparty/freetype/src/cff/cffgload.h32
-rw-r--r--src/3rdparty/freetype/src/cff/cffload.c61
-rw-r--r--src/3rdparty/freetype/src/cff/cffload.h32
-rw-r--r--src/3rdparty/freetype/src/cff/cffobjs.c118
-rw-r--r--src/3rdparty/freetype/src/cff/cffobjs.h48
-rw-r--r--src/3rdparty/freetype/src/cff/cffparse.c444
-rw-r--r--src/3rdparty/freetype/src/cff/cffparse.h55
-rw-r--r--src/3rdparty/freetype/src/cff/cfftoken.h32
-rw-r--r--src/3rdparty/freetype/src/cff/module.mk2
-rw-r--r--src/3rdparty/freetype/src/cff/rules.mk5
-rw-r--r--src/3rdparty/freetype/src/cid/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/cid/ciderrs.h46
-rw-r--r--src/3rdparty/freetype/src/cid/cidgload.c49
-rw-r--r--src/3rdparty/freetype/src/cid/cidgload.h32
-rw-r--r--src/3rdparty/freetype/src/cid/cidload.c185
-rw-r--r--src/3rdparty/freetype/src/cid/cidload.h32
-rw-r--r--src/3rdparty/freetype/src/cid/cidobjs.c204
-rw-r--r--src/3rdparty/freetype/src/cid/cidobjs.h116
-rw-r--r--src/3rdparty/freetype/src/cid/cidparse.c46
-rw-r--r--src/3rdparty/freetype/src/cid/cidparse.h108
-rw-r--r--src/3rdparty/freetype/src/cid/cidriver.c56
-rw-r--r--src/3rdparty/freetype/src/cid/cidriver.h38
-rw-r--r--src/3rdparty/freetype/src/cid/cidtoken.h57
-rw-r--r--src/3rdparty/freetype/src/cid/module.mk2
-rw-r--r--src/3rdparty/freetype/src/cid/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/cid/type1cid.c32
-rw-r--r--src/3rdparty/freetype/src/gxvalid/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/gxvalid/README2
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvalid.c34
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvalid.h50
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvbsln.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvcommn.c68
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvcommn.h60
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxverror.h66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvfeat.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvfeat.h50
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvfgen.c114
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvjust.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvkern.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvlcar.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmod.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmod.h56
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmort.c65
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmort.h50
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmort0.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmort1.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmort2.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmort4.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmort5.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmorx.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmorx.h50
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmorx0.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmorx1.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmorx2.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmorx4.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvmorx5.c66
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvopbd.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvprop.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/gxvtrak.c64
-rw-r--r--src/3rdparty/freetype/src/gxvalid/module.mk2
-rw-r--r--src/3rdparty/freetype/src/gxvalid/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/gzip/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/gzip/ftgzip.c64
-rw-r--r--src/3rdparty/freetype/src/gzip/infblock.c5
-rw-r--r--src/3rdparty/freetype/src/gzip/infcodes.c4
-rw-r--r--src/3rdparty/freetype/src/gzip/inflate.c10
-rw-r--r--src/3rdparty/freetype/src/gzip/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/lzw/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/lzw/ftlzw.c56
-rw-r--r--src/3rdparty/freetype/src/lzw/ftzopen.c48
-rw-r--r--src/3rdparty/freetype/src/lzw/ftzopen.h116
-rw-r--r--src/3rdparty/freetype/src/lzw/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/otvalid/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/otvalid/module.mk2
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvalid.c32
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvalid.h32
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvbase.c46
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvcommn.c46
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvcommn.h32
-rw-r--r--src/3rdparty/freetype/src/otvalid/otverror.h48
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvgdef.c46
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvgpos.c46
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvgpos.h32
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvgsub.c46
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvjstf.c46
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvmath.c50
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvmod.c46
-rw-r--r--src/3rdparty/freetype/src/otvalid/otvmod.h38
-rw-r--r--src/3rdparty/freetype/src/otvalid/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/pcf/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/pcf/pcf.h59
-rw-r--r--src/3rdparty/freetype/src/pcf/pcfdrivr.c163
-rw-r--r--src/3rdparty/freetype/src/pcf/pcfdrivr.h5
-rw-r--r--src/3rdparty/freetype/src/pcf/pcferror.h46
-rw-r--r--src/3rdparty/freetype/src/pcf/pcfread.c407
-rw-r--r--src/3rdparty/freetype/src/pcf/pcfutil.c6
-rw-r--r--src/3rdparty/freetype/src/pfr/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/pfr/module.mk2
-rw-r--r--src/3rdparty/freetype/src/pfr/pfr.c32
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrcmap.c32
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrcmap.h32
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrdrivr.c48
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrdrivr.h38
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrerror.h46
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrgload.c52
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrgload.h32
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrload.c162
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrload.h32
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrobjs.c40
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrobjs.h32
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrsbit.c34
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrsbit.h32
-rw-r--r--src/3rdparty/freetype/src/pfr/pfrtypes.h32
-rw-r--r--src/3rdparty/freetype/src/pfr/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/psaux/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/psaux/afmparse.c59
-rw-r--r--src/3rdparty/freetype/src/psaux/afmparse.h32
-rw-r--r--src/3rdparty/freetype/src/psaux/cffdecode.c300
-rw-r--r--src/3rdparty/freetype/src/psaux/cffdecode.h32
-rw-r--r--src/3rdparty/freetype/src/psaux/module.mk2
-rw-r--r--src/3rdparty/freetype/src/psaux/psarrst.c72
-rw-r--r--src/3rdparty/freetype/src/psaux/psarrst.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/psaux.c32
-rw-r--r--src/3rdparty/freetype/src/psaux/psauxerr.h48
-rw-r--r--src/3rdparty/freetype/src/psaux/psauxmod.c32
-rw-r--r--src/3rdparty/freetype/src/psaux/psauxmod.h36
-rw-r--r--src/3rdparty/freetype/src/psaux/psblues.c100
-rw-r--r--src/3rdparty/freetype/src/psaux/psblues.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/psconv.c46
-rw-r--r--src/3rdparty/freetype/src/psaux/psconv.h32
-rw-r--r--src/3rdparty/freetype/src/psaux/pserror.c72
-rw-r--r--src/3rdparty/freetype/src/psaux/pserror.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/psfixed.h75
-rw-r--r--src/3rdparty/freetype/src/psaux/psfont.c82
-rw-r--r--src/3rdparty/freetype/src/psaux/psfont.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/psft.c95
-rw-r--r--src/3rdparty/freetype/src/psaux/psft.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/psglue.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/pshints.c117
-rw-r--r--src/3rdparty/freetype/src/psaux/pshints.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/psintrp.c148
-rw-r--r--src/3rdparty/freetype/src/psaux/psintrp.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/psobjs.c486
-rw-r--r--src/3rdparty/freetype/src/psaux/psobjs.h40
-rw-r--r--src/3rdparty/freetype/src/psaux/psread.c74
-rw-r--r--src/3rdparty/freetype/src/psaux/psread.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/psstack.c75
-rw-r--r--src/3rdparty/freetype/src/psaux/psstack.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/pstypes.h72
-rw-r--r--src/3rdparty/freetype/src/psaux/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/psaux/t1cmap.c35
-rw-r--r--src/3rdparty/freetype/src/psaux/t1cmap.h32
-rw-r--r--src/3rdparty/freetype/src/psaux/t1decode.c341
-rw-r--r--src/3rdparty/freetype/src/psaux/t1decode.h32
-rw-r--r--src/3rdparty/freetype/src/pshinter/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/pshinter/module.mk2
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshalgo.c50
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshalgo.h32
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshglob.c39
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshglob.h68
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshinter.c33
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshmod.c35
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshmod.h32
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshnterr.h46
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshrec.c38
-rw-r--r--src/3rdparty/freetype/src/pshinter/pshrec.h56
-rw-r--r--src/3rdparty/freetype/src/pshinter/rules.mk3
-rw-r--r--src/3rdparty/freetype/src/psnames/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/psnames/module.mk2
-rw-r--r--src/3rdparty/freetype/src/psnames/psmodule.c73
-rw-r--r--src/3rdparty/freetype/src/psnames/psmodule.h32
-rw-r--r--src/3rdparty/freetype/src/psnames/psnamerr.h48
-rw-r--r--src/3rdparty/freetype/src/psnames/psnames.c33
-rw-r--r--src/3rdparty/freetype/src/psnames/pstables.h44
-rw-r--r--src/3rdparty/freetype/src/psnames/rules.mk21
-rw-r--r--src/3rdparty/freetype/src/raster/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/raster/ftmisc.h50
-rw-r--r--src/3rdparty/freetype/src/raster/ftraster.c1285
-rw-r--r--src/3rdparty/freetype/src/raster/ftraster.h42
-rw-r--r--src/3rdparty/freetype/src/raster/ftrend1.c41
-rw-r--r--src/3rdparty/freetype/src/raster/ftrend1.h32
-rw-r--r--src/3rdparty/freetype/src/raster/module.mk2
-rw-r--r--src/3rdparty/freetype/src/raster/raster.c33
-rw-r--r--src/3rdparty/freetype/src/raster/rasterrs.h48
-rw-r--r--src/3rdparty/freetype/src/raster/rules.mk5
-rw-r--r--src/3rdparty/freetype/src/sfnt/Jamfile4
-rw-r--r--src/3rdparty/freetype/src/sfnt/module.mk2
-rw-r--r--src/3rdparty/freetype/src/sfnt/pngshim.c34
-rw-r--r--src/3rdparty/freetype/src/sfnt/pngshim.h34
-rw-r--r--src/3rdparty/freetype/src/sfnt/rules.mk22
-rw-r--r--src/3rdparty/freetype/src/sfnt/sfdriver.c259
-rw-r--r--src/3rdparty/freetype/src/sfnt/sfdriver.h34
-rw-r--r--src/3rdparty/freetype/src/sfnt/sferrors.h46
-rw-r--r--src/3rdparty/freetype/src/sfnt/sfnt.c37
-rw-r--r--src/3rdparty/freetype/src/sfnt/sfobjs.c654
-rw-r--r--src/3rdparty/freetype/src/sfnt/sfobjs.h34
-rw-r--r--src/3rdparty/freetype/src/sfnt/sfwoff.c434
-rw-r--r--src/3rdparty/freetype/src/sfnt/sfwoff.h41
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttbdf.c54
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttbdf.h32
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttcmap.c656
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttcmap.h70
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttcmapc.h32
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttcolr.c451
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttcolr.h58
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttcpal.c311
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttcpal.h49
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttkern.c56
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttkern.h34
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttload.c569
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttload.h34
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttmtx.c187
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttmtx.h32
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttpost.c117
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttpost.h34
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttsbit.c64
-rw-r--r--src/3rdparty/freetype/src/sfnt/ttsbit.h32
-rw-r--r--src/3rdparty/freetype/src/smooth/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/smooth/ftgrays.c724
-rw-r--r--src/3rdparty/freetype/src/smooth/ftgrays.h49
-rw-r--r--src/3rdparty/freetype/src/smooth/ftsmerrs.h48
-rw-r--r--src/3rdparty/freetype/src/smooth/ftsmooth.c127
-rw-r--r--src/3rdparty/freetype/src/smooth/ftsmooth.h32
-rw-r--r--src/3rdparty/freetype/src/smooth/module.mk2
-rw-r--r--src/3rdparty/freetype/src/smooth/rules.mk5
-rw-r--r--src/3rdparty/freetype/src/smooth/smooth.c33
-rw-r--r--src/3rdparty/freetype/src/tools/afblue.pl2
-rw-r--r--src/3rdparty/freetype/src/tools/apinames.c441
-rw-r--r--src/3rdparty/freetype/src/tools/glnames.py50
-rw-r--r--src/3rdparty/freetype/src/tools/update-copyright-year19
-rw-r--r--src/3rdparty/freetype/src/truetype/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/truetype/module.mk2
-rw-r--r--src/3rdparty/freetype/src/truetype/rules.mk3
-rw-r--r--src/3rdparty/freetype/src/truetype/truetype.c33
-rw-r--r--src/3rdparty/freetype/src/truetype/ttdriver.c224
-rw-r--r--src/3rdparty/freetype/src/truetype/ttdriver.h34
-rw-r--r--src/3rdparty/freetype/src/truetype/tterrors.h48
-rw-r--r--src/3rdparty/freetype/src/truetype/ttgload.c555
-rw-r--r--src/3rdparty/freetype/src/truetype/ttgload.h32
-rw-r--r--src/3rdparty/freetype/src/truetype/ttgxvar.c1436
-rw-r--r--src/3rdparty/freetype/src/truetype/ttgxvar.h313
-rw-r--r--src/3rdparty/freetype/src/truetype/ttinterp.c3609
-rw-r--r--src/3rdparty/freetype/src/truetype/ttinterp.h168
-rw-r--r--src/3rdparty/freetype/src/truetype/ttobjs.c493
-rw-r--r--src/3rdparty/freetype/src/truetype/ttobjs.h312
-rw-r--r--src/3rdparty/freetype/src/truetype/ttpload.c244
-rw-r--r--src/3rdparty/freetype/src/truetype/ttpload.h32
-rw-r--r--src/3rdparty/freetype/src/truetype/ttsubpix.c90
-rw-r--r--src/3rdparty/freetype/src/truetype/ttsubpix.h52
-rw-r--r--src/3rdparty/freetype/src/type1/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/type1/module.mk2
-rw-r--r--src/3rdparty/freetype/src/type1/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/type1/t1afm.c46
-rw-r--r--src/3rdparty/freetype/src/type1/t1afm.h32
-rw-r--r--src/3rdparty/freetype/src/type1/t1driver.c217
-rw-r--r--src/3rdparty/freetype/src/type1/t1driver.h38
-rw-r--r--src/3rdparty/freetype/src/type1/t1errors.h46
-rw-r--r--src/3rdparty/freetype/src/type1/t1gload.c77
-rw-r--r--src/3rdparty/freetype/src/type1/t1gload.h32
-rw-r--r--src/3rdparty/freetype/src/type1/t1load.c451
-rw-r--r--src/3rdparty/freetype/src/type1/t1load.h42
-rw-r--r--src/3rdparty/freetype/src/type1/t1objs.c213
-rw-r--r--src/3rdparty/freetype/src/type1/t1objs.h132
-rw-r--r--src/3rdparty/freetype/src/type1/t1parse.c110
-rw-r--r--src/3rdparty/freetype/src/type1/t1parse.h101
-rw-r--r--src/3rdparty/freetype/src/type1/t1tokens.h32
-rw-r--r--src/3rdparty/freetype/src/type1/type1.c32
-rw-r--r--src/3rdparty/freetype/src/type42/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/type42/module.mk2
-rw-r--r--src/3rdparty/freetype/src/type42/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/type42/t42drivr.c86
-rw-r--r--src/3rdparty/freetype/src/type42/t42drivr.h38
-rw-r--r--src/3rdparty/freetype/src/type42/t42error.h46
-rw-r--r--src/3rdparty/freetype/src/type42/t42objs.c87
-rw-r--r--src/3rdparty/freetype/src/type42/t42objs.h32
-rw-r--r--src/3rdparty/freetype/src/type42/t42parse.c100
-rw-r--r--src/3rdparty/freetype/src/type42/t42parse.h32
-rw-r--r--src/3rdparty/freetype/src/type42/t42types.h32
-rw-r--r--src/3rdparty/freetype/src/type42/type42.c32
-rw-r--r--src/3rdparty/freetype/src/winfonts/Jamfile2
-rw-r--r--src/3rdparty/freetype/src/winfonts/fnterrs.h48
-rw-r--r--src/3rdparty/freetype/src/winfonts/module.mk2
-rw-r--r--src/3rdparty/freetype/src/winfonts/rules.mk2
-rw-r--r--src/3rdparty/freetype/src/winfonts/winfnt.c58
-rw-r--r--src/3rdparty/freetype/src/winfonts/winfnt.h40
505 files changed, 38384 insertions, 34945 deletions
diff --git a/src/3rdparty/freetype/README b/src/3rdparty/freetype/README
index c23b99e18a..8f3e2bc03b 100644
--- a/src/3rdparty/freetype/README
+++ b/src/3rdparty/freetype/README
@@ -1,5 +1,5 @@
- FreeType 2.9.1
- ==============
+ FreeType 2.10.1
+ ===============
Homepage: https://www.freetype.org
@@ -15,8 +15,8 @@
Read the files `docs/INSTALL*' for installation instructions; see
the file `docs/LICENSE.TXT' for the available licenses.
- The FreeType 2 API reference is located in `docs/reference'; use the
- file `ft2-toc.html' as the top entry point. Additional
+ The FreeType 2 API reference is located in `docs/reference/site';
+ use the file `index.html' as the top entry point. Additional
documentation is available as a separate package from our sites. Go
to
@@ -24,13 +24,13 @@
and download one of the following files.
- freetype-doc-2.9.1.tar.bz2
- freetype-doc-2.9.1.tar.gz
- ftdoc291.zip
+ freetype-doc-2.10.1.tar.xz
+ freetype-doc-2.10.1.tar.gz
+ ftdoc2101.zip
To view the documentation online, go to
- https://www.freetype.org/freetype2/documentation.html
+ https://www.freetype.org/freetype2/docs/
Mailing Lists
@@ -71,7 +71,7 @@
----------------------------------------------------------------------
-Copyright 2006-2018 by
+Copyright (C) 2006-2019 by
David Turner, Robert Wilhelm, and Werner Lemberg.
This file is part of the FreeType project, and may only be used,
diff --git a/src/3rdparty/freetype/builds/unix/ftsystem.c b/src/3rdparty/freetype/builds/unix/ftsystem.c
index 8fdbeb0f62..826713f948 100644
--- a/src/3rdparty/freetype/builds/unix/ftsystem.c
+++ b/src/3rdparty/freetype/builds/unix/ftsystem.c
@@ -4,7 +4,7 @@
/* */
/* Unix-specific FreeType low-level system interface (body). */
/* */
-/* Copyright 1996-2018 by */
+/* Copyright (C) 1996-2019 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
/* */
/* This file is part of the FreeType project, and may only be used, */
@@ -173,7 +173,7 @@
/* messages during execution. */
/* */
#undef FT_COMPONENT
-#define FT_COMPONENT trace_io
+#define FT_COMPONENT io
/* We use the macro STREAM_FILE for convenience to extract the */
/* system-specific stream handle from a given FreeType stream object */
diff --git a/src/3rdparty/freetype/docs/CHANGES b/src/3rdparty/freetype/docs/CHANGES
index a6d088af49..f36cb19b7e 100644
--- a/src/3rdparty/freetype/docs/CHANGES
+++ b/src/3rdparty/freetype/docs/CHANGES
@@ -1,3 +1,184 @@
+
+CHANGES BETWEEN 2.10.0 and 2.10.1
+
+ I. IMPORTANT BUG FIXES
+
+ - The bytecode hinting of OpenType variation fonts was flawed, since
+ the data in the `CVAR' table wasn't correctly applied.
+
+
+ II. MISCELLANEOUS
+
+ - Auto-hinter support for Mongolian.
+
+ - For distribution, `.tar.bz2' packages are replaced with `.tar.xz'
+ bundles.
+
+ - The handling of the default character in PCF fonts as introduced
+ in version 2.10.0 was partially broken, causing premature abortion
+ of charmap iteration for many fonts.
+
+ - If `FT_Set_Named_Instance' was called with the same arguments
+ twice in a row, the function returned an incorrect error code the
+ second time.
+
+ - Direct rendering using FT_RASTER_FLAG_DIRECT crashed (bug
+ introduced in version 2.10.0).
+
+ - Increased precision while computing OpenType font variation
+ instances.
+
+ - The flattening algorithm of cubic Bezier curves was slightly
+ changed to make it faster. This can cause very subtle rendering
+ changes, which aren't noticeable by the eye, however.
+
+ - The auto-hinter now disables hinting if there are blue zones
+ defined for a `style' (i.e., a certain combination of a script and
+ its related typographic features) but the font doesn't contain any
+ characters needed to set up at least one blue zone.
+
+ - The `ftmulti' demo program now supports multiple hidden axes with
+ the same name tag.
+
+ - `ftview', `ftstring', and `ftgrid' got a `-k' command line option
+ to emulate a sequence of keystrokes at start-up.
+
+ - `ftview', `ftstring', and `ftgrid' now support screen dumping to a
+ PNG file.
+
+ - The bytecode debugger, `ttdebug', now supports variation TrueType
+ fonts; a variation font instance can be selected with the new `-d'
+ command line option.
+
+
+======================================================================
+
+CHANGES BETWEEN 2.9.1 and 2.10.0
+
+ I. IMPORTANT CHANGES
+
+ - A bunch of new functions has been added to access and process
+ COLR/CPAL data of OpenType fonts with color-layered glyphs.
+
+ FT_Palette_Data_Get
+ Retrieve color palette data.
+ FT_Palette_Select
+ Select and activate a color palette for color-layered
+ glyphs.
+ FT_Palette_Set_Foreground_Color
+ Set text foreground color for palette index 0xFFFF.
+
+ FT_Get_Color_Glyph_Layer
+ Get color layers for a given glyph (using an interator
+ object).
+
+ FT_Bitmap_Blend
+ Blend one bitmap onto another with a given color.
+
+ - An experimental feature is the new behaviour of the
+ `FT_LOAD_COLOR' load flag for color-layered glyphs: Internally
+ it sets a flag so that if `FT_Render_Glyph' is called with
+ `FT_RENDER_MODE_NORMAL' (or `FT_Load_Glyph' with
+ `FT_LOAD_RENDER'), a default blending of the color glyph layers
+ will happen automatically for convenience.
+
+ - As a GSoC 2018 project, Nikhil Ramakrishnan completely
+ overhauled and modernized the API reference.
+
+
+ II. MISCELLANEOUS
+
+ - The logic for computing the global ascender, descender, and
+ height of OpenType fonts has been slightly adjusted for
+ consistency.
+
+ . If the `useTypoMetrics' flag (i.e., bit 7 in the `fsSelection'
+ field) in the `OS/2' table is set, use the `sTypo' fields in
+ `OS/2' unconditionally.
+ . Otherwise use the metrics data from the `hhea' table (if not
+ zero).
+ . Otherwise use the `sTypo' fields from the `OS/2' table (if not
+ zero).
+ . Otherwise use the `usWin' data from the `OS/2' table as a last
+ resort.
+
+ Variable fonts will apply the `MVAR' deltas to whichever metrics
+ were picked.
+
+ - `TT_Set_MM_Blend' could fail if call repeatedly with the same
+ arguments.
+
+ - The precision of handling deltas in Variation Fonts has been
+ increased. The problem did only show up with multidimensional
+ designspaces.
+
+ - New function `FT_Library_SetLcdGeometry' to set up the geometry
+ of LCD subpixels.
+
+ - FreeType now uses the `defaultChar' property of PCF fonts to set
+ the glyph for the undefined character at glyph index 0 (as
+ FreeType already does for all other supported font formats). As
+ a consequence, the order of glyphs of a PCF font if accessed
+ with FreeType can be different now compared to previous
+ versions.
+
+ This change doesn't affect PCF font access with cmaps.
+
+ - `FT_Select_Charmap' has been changed to allow parameter value
+ `FT_ENCODING_NONE', which is valid for BDF, PCF, and Windows FNT
+ formats to access built-in cmaps that don't have a predefined
+ `FT_Encoding' value.
+
+ - A previously reserved field in the `FT_GlyphSlotRec' structure
+ now holds the glyph index.
+
+ - On Win32 platforms, the use of `_DLL' to build the library has
+ been replaced with `DLL_EXPORT' and `DLL_IMPORT'.
+
+ - The usual round of fuzzer bug fixes to better reject malformed
+ fonts.
+
+ - `FT_Outline_New_Internal' and `FT_Outline_Done_Internal' have
+ been removed. These two functions were public by oversight only
+ and were never documented.
+
+ - A new function `FT_Error_String' returns descriptions of error
+ codes if configuration macro FT_CONFIG_OPTION_ERROR_STRINGS is
+ defined.
+
+ - `FT_Set_MM_WeightVector' and `FT_Get_MM_WeightVector' are new
+ functions limited to Adobe MultiMaster fonts to directly set and
+ get the weight vector.
+
+ - Support for Position Independent Code as needed by systems that
+ prohibit automatic address fixups, such as BREW, has been
+ removed. [Compilation with modern compilers that use flags like
+ `-fPIC' or `-fPIE' is not affected.]
+
+ - The `ftdump' demo program has new options `-c' and `-C' to
+ display charmaps in compact and detailed format, respectively.
+ Option `-V' has been removed.
+
+ - The `ftview', `ftstring', and `ftgrid' demo programs use a new
+ command line option `-d' to specify the program window's width,
+ height, and color depth.
+
+ - The `ftview' demo program now displays red boxes for zero-width
+ glyphs.
+
+ - `ftglyph' has limited support to display fonts with
+ color-layered glyphs. This will be improved later on.
+
+ - `ftgrid' can now display bitmap fonts also.
+
+ - The `ttdebug' demo program has a new option `-f' to select a
+ member of a TrueType collection (TTC).
+
+ - Other various improvements to the demo programs.
+
+
+======================================================================
+
CHANGES BETWEEN 2.9 and 2.9.1
I. IMPORTANT BUG FIXES
@@ -8,7 +189,7 @@ CHANGES BETWEEN 2.9 and 2.9.1
- CVE-2018-6942: Older FreeType versions can crash with certain
malformed variation fonts.
- http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-6942
+ https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-6942
II. MISCELLANEOUS
@@ -232,7 +413,7 @@ CHANGES BETWEEN 2.7.1 and 2.8
following properties can be handled: stem darkening, LCD filter
weights, and the random seed for the `random' CFF operator.
- - The PCF change to show more `colourful' family names (introduced
+ - The PCF change to show more `colorful' family names (introduced
in version 2.7.1) was too radical; it can now be configured with
PCF_CONFIG_OPTION_LONG_FAMILY_NAMES at compile time. If
activated, it can be switched off at run time with the new pcf
@@ -383,7 +564,7 @@ CHANGES BETWEEN 2.7 and 2.7.1
and the number of CVT entries. Please report if you encounter a
font where the selected values are not adequate.
- - PCF family names are made more `colourful'; they now include the
+ - PCF family names are made more `colorful'; they now include the
foundry and information whether they contain wide characters.
For example, you no longer get `Fixed' but rather `Sony Fixed'
or `Misc Fixed Wide'.
@@ -667,8 +848,8 @@ CHANGES BETWEEN 2.6.1 and 2.6.2
- The `ftstring' demo program now supports subpixel rendering; use
key `l' to cycle through the LCD modes.
- - The `ftstring' demo program now supports colour rendering; use
- the `space' key to cycle through various colour combinations.
+ - The `ftstring' demo program now supports color rendering; use
+ the `space' key to cycle through various color combinations.
- The graphical demo programs now use a default gamma value of 1.8
(instead of 1.2).
@@ -1325,7 +1506,7 @@ CHANGES BETWEEN 2.4.10 and 2.4.11
Originally, it was a separate patch available from
- http://www.infinality.net/blog/
+ https://web.archive.org/web/20150710073951/http://www.infinality.net:80/blog/
and which has been integrated.
@@ -4047,7 +4228,7 @@ CHANGES BETWEEN beta8 and 2.0
untested for now.
- Updated `docs/docmaker.py', a draft API reference is available at
- http://www.freetype.org/ft2api.html.
+ https://web.archive.org/web/20001215173400/http://www.freetype.org:80/ft2api.html.
- Changed `type1' to use `psaux'.
@@ -5017,7 +5198,7 @@ Extensions support:
------------------------------------------------------------------------
-Copyright 2000-2018 by
+Copyright (C) 2000-2019 by
David Turner, Robert Wilhelm, and Werner Lemberg.
This file is part of the FreeType project, and may only be used,
diff --git a/src/3rdparty/freetype/docs/CUSTOMIZE b/src/3rdparty/freetype/docs/CUSTOMIZE
index 916be32754..f3f9f8edc1 100644
--- a/src/3rdparty/freetype/docs/CUSTOMIZE
+++ b/src/3rdparty/freetype/docs/CUSTOMIZE
@@ -139,7 +139,7 @@ IV. Overriding default configuration and module headers
----------------------------------------------------------------------
-Copyright 2003-2018 by
+Copyright (C) 2003-2019 by
David Turner, Robert Wilhelm, and Werner Lemberg.
This file is part of the FreeType project, and may only be used,
diff --git a/src/3rdparty/freetype/docs/DEBUG b/src/3rdparty/freetype/docs/DEBUG
index 751eaf028a..828f29434d 100644
--- a/src/3rdparty/freetype/docs/DEBUG
+++ b/src/3rdparty/freetype/docs/DEBUG
@@ -88,14 +88,13 @@ debugging its code:
for example as in
#undef FT_COMPONENT
- #define FT_COMPONENT trace_io
-
- The value of the FT_COMPONENT macro is an enumeration named
- `trace_XXXX' where `XXXX' is one of the component names defined in
- the internal file `internal/fttrace.h'. If you modify FreeType
- source and insert new `trace_XXXX' macro, you must register it in
- `fttrace.h'. If you insert or remove many trace macros, you can
- check the undefined or the unused trace macro by
+ #define FT_COMPONENT io
+
+ The value of the FT_COMPONENT macro is one of the component
+ names defined in the internal file `internal/fttrace.h'. If you
+ modify FreeType source and insert new FT_COMPONENT macro, you must
+ register it in `fttrace.h'. If you insert or remove many trace
+ macros, you can check the undefined or the unused trace macro by
`src/tools/chktrcmp.py'.
Each such component is assigned a `debug level', ranging from 0 to
@@ -138,8 +137,8 @@ behaviour of FreeType at runtime.
component1:level1 component2:level2 component3:level3 ...
where `componentX' is the name of a tracing component, as defined
- in `fttrace.h', but without the `trace_' prefix. `levelX' is the
- corresponding level to use at runtime.
+ in `fttrace.h'. `levelX' is the corresponding level to use at
+ runtime.
`any' is a special component name that will be interpreted as
`any/all components'. For example, the following definitions
@@ -191,7 +190,7 @@ behaviour of FreeType at runtime.
------------------------------------------------------------------------
-Copyright 2002-2018 by
+Copyright (C) 2002-2019 by
David Turner, Robert Wilhelm, and Werner Lemberg.
This file is part of the FreeType project, and may only be used,
diff --git a/src/3rdparty/freetype/docs/TODO b/src/3rdparty/freetype/docs/TODO
index 1a443a2edc..1efccc68eb 100644
--- a/src/3rdparty/freetype/docs/TODO
+++ b/src/3rdparty/freetype/docs/TODO
@@ -27,7 +27,7 @@ Other bugs have been registered at the savannah bugzilla of FreeType.
------------------------------------------------------------------------
-Copyright 2001-2018 by
+Copyright (C) 2001-2019 by
David Turner, Robert Wilhelm, and Werner Lemberg.
This file is part of the FreeType project, and may only be used,
diff --git a/src/3rdparty/freetype/include/freetype/config/ftconfig.h b/src/3rdparty/freetype/include/freetype/config/ftconfig.h
index eedebf4082..9466603377 100644
--- a/src/3rdparty/freetype/include/freetype/config/ftconfig.h
+++ b/src/3rdparty/freetype/include/freetype/config/ftconfig.h
@@ -1,39 +1,38 @@
-/***************************************************************************/
-/* */
-/* ftconfig.h */
-/* */
-/* ANSI-specific configuration file (specification only). */
-/* */
-/* Copyright 1996-2018 by */
-/* David Turner, Robert Wilhelm, and Werner Lemberg. */
-/* */
-/* This file is part of the FreeType project, and may only be used, */
-/* modified, and distributed under the terms of the FreeType project */
-/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
-/* this file you indicate that you have read the license and */
-/* understand and accept it fully. */
-/* */
-/***************************************************************************/
-
-
- /*************************************************************************/
- /* */
- /* This header file contains a number of macro definitions that are used */
- /* by the rest of the engine. Most of the macros here are automatically */
- /* determined at compile time, and you should not need to change it to */
- /* port FreeType, except to compile the library with a non-ANSI */
- /* compiler. */
- /* */
- /* Note however that if some specific modifications are needed, we */
- /* advise you to place a modified copy in your build directory. */
- /* */
- /* The build directory is usually `builds/<system>', and contains */
- /* system-specific files that are always included first when building */
- /* the library. */
- /* */
- /* This ANSI version should stay in `include/config/'. */
- /* */
- /*************************************************************************/
+/****************************************************************************
+ *
+ * ftconfig.h
+ *
+ * ANSI-specific configuration file (specification only).
+ *
+ * Copyright (C) 1996-2019 by
+ * David Turner, Robert Wilhelm, and Werner Lemberg.
+ *
+ * This file is part of the FreeType project, and may only be used,
+ * modified, and distributed under the terms of the FreeType project
+ * license, LICENSE.TXT. By continuing to use, modify, or distribute
+ * this file you indicate that you have read the license and
+ * understand and accept it fully.
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * This header file contains a number of macro definitions that are used by
+ * the rest of the engine. Most of the macros here are automatically
+ * determined at compile time, and you should not need to change it to port
+ * FreeType, except to compile the library with a non-ANSI compiler.
+ *
+ * Note however that if some specific modifications are needed, we advise
+ * you to place a modified copy in your build directory.
+ *
+ * The build directory is usually `builds/<system>`, and contains
+ * system-specific files that are always included first when building the
+ * library.
+ *
+ * This ANSI version should stay in `include/config/`.
+ *
+ */
#ifndef FTCONFIG_H_
#define FTCONFIG_H_
@@ -46,32 +45,32 @@
FT_BEGIN_HEADER
- /*************************************************************************/
- /* */
- /* PLATFORM-SPECIFIC CONFIGURATION MACROS */
- /* */
- /* These macros can be toggled to suit a specific system. The current */
- /* ones are defaults used to compile FreeType in an ANSI C environment */
- /* (16bit compilers are also supported). Copy this file to your own */
- /* `builds/<system>' directory, and edit it to port the engine. */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * PLATFORM-SPECIFIC CONFIGURATION MACROS
+ *
+ * These macros can be toggled to suit a specific system. The current ones
+ * are defaults used to compile FreeType in an ANSI C environment (16bit
+ * compilers are also supported). Copy this file to your own
+ * `builds/<system>` directory, and edit it to port the engine.
+ *
+ */
- /* There are systems (like the Texas Instruments 'C54x) where a `char' */
- /* has 16 bits. ANSI C says that sizeof(char) is always 1. Since an */
- /* `int' has 16 bits also for this system, sizeof(int) gives 1 which */
- /* is probably unexpected. */
- /* */
- /* `CHAR_BIT' (defined in limits.h) gives the number of bits in a */
- /* `char' type. */
+ /* There are systems (like the Texas Instruments 'C54x) where a `char` */
+ /* has 16~bits. ANSI~C says that `sizeof(char)` is always~1. Since an */
+ /* `int` has 16~bits also for this system, `sizeof(int)` gives~1 which */
+ /* is probably unexpected. */
+ /* */
+ /* `CHAR_BIT` (defined in `limits.h`) gives the number of bits in a */
+ /* `char` type. */
#ifndef FT_CHAR_BIT
#define FT_CHAR_BIT CHAR_BIT
#endif
- /* The size of an `int' type. */
+ /* The size of an `int` type. */
#if FT_UINT_MAX == 0xFFFFUL
#define FT_SIZEOF_INT ( 16 / FT_CHAR_BIT )
#elif FT_UINT_MAX == 0xFFFFFFFFUL
@@ -82,7 +81,7 @@ FT_BEGIN_HEADER
#error "Unsupported size of `int' type!"
#endif
- /* The size of a `long' type. A five-byte `long' (as used e.g. on the */
+ /* The size of a `long` type. A five-byte `long` (as used e.g. on the */
/* DM642) is recognized but avoided. */
#if FT_ULONG_MAX == 0xFFFFFFFFUL
#define FT_SIZEOF_LONG ( 32 / FT_CHAR_BIT )
@@ -95,35 +94,35 @@ FT_BEGIN_HEADER
#endif
- /* FT_UNUSED is a macro used to indicate that a given parameter is not */
- /* used -- this is only used to get rid of unpleasant compiler warnings */
+ /* `FT_UNUSED` indicates that a given parameter is not used -- */
+ /* this is only used to get rid of unpleasant compiler warnings. */
#ifndef FT_UNUSED
#define FT_UNUSED( arg ) ( (arg) = (arg) )
#endif
- /*************************************************************************/
- /* */
- /* AUTOMATIC CONFIGURATION MACROS */
- /* */
- /* These macros are computed from the ones defined above. Don't touch */
- /* their definition, unless you know precisely what you are doing. No */
- /* porter should need to mess with them. */
- /* */
- /*************************************************************************/
-
-
- /*************************************************************************/
- /* */
- /* Mac support */
- /* */
- /* This is the only necessary change, so it is defined here instead */
- /* providing a new configuration file. */
- /* */
+ /**************************************************************************
+ *
+ * AUTOMATIC CONFIGURATION MACROS
+ *
+ * These macros are computed from the ones defined above. Don't touch
+ * their definition, unless you know precisely what you are doing. No
+ * porter should need to mess with them.
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * Mac support
+ *
+ * This is the only necessary change, so it is defined here instead
+ * providing a new configuration file.
+ */
#if defined( __APPLE__ ) || ( defined( __MWERKS__ ) && defined( macintosh ) )
- /* no Carbon frameworks for 64bit 10.4.x */
- /* AvailabilityMacros.h is available since Mac OS X 10.2, */
- /* so guess the system version by maximum errno before inclusion */
+ /* No Carbon frameworks for 64bit 10.4.x. */
+ /* `AvailabilityMacros.h` is available since Mac OS X 10.2, */
+ /* so guess the system version by maximum errno before inclusion. */
#include <errno.h>
#ifdef ECANCELED /* defined since 10.2 */
#include "AvailabilityMacros.h"
@@ -143,7 +142,7 @@ FT_BEGIN_HEADER
#endif
- /* Fix compiler warning with sgi compiler */
+ /* Fix compiler warning with sgi compiler. */
#if defined( __sgi ) && !defined( __GNUC__ )
#if defined( _COMPILER_VERSION ) && ( _COMPILER_VERSION >= 730 )
#pragma set woff 3505
@@ -151,33 +150,33 @@ FT_BEGIN_HEADER
#endif
- /*************************************************************************/
- /* */
- /* <Section> */
- /* basic_types */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * basic_types
+ *
+ */
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Int16 */
- /* */
- /* <Description> */
- /* A typedef for a 16bit signed integer type. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Int16
+ *
+ * @description:
+ * A typedef for a 16bit signed integer type.
+ */
typedef signed short FT_Int16;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_UInt16 */
- /* */
- /* <Description> */
- /* A typedef for a 16bit unsigned integer type. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_UInt16
+ *
+ * @description:
+ * A typedef for a 16bit unsigned integer type.
+ */
typedef unsigned short FT_UInt16;
/* */
@@ -186,50 +185,50 @@ FT_BEGIN_HEADER
/* this #if 0 ... #endif clause is for documentation purposes */
#if 0
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Int32 */
- /* */
- /* <Description> */
- /* A typedef for a 32bit signed integer type. The size depends on */
- /* the configuration. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Int32
+ *
+ * @description:
+ * A typedef for a 32bit signed integer type. The size depends on the
+ * configuration.
+ */
typedef signed XXX FT_Int32;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_UInt32 */
- /* */
- /* A typedef for a 32bit unsigned integer type. The size depends on */
- /* the configuration. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_UInt32
+ *
+ * A typedef for a 32bit unsigned integer type. The size depends on the
+ * configuration.
+ */
typedef unsigned XXX FT_UInt32;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Int64 */
- /* */
- /* A typedef for a 64bit signed integer type. The size depends on */
- /* the configuration. Only defined if there is real 64bit support; */
- /* otherwise, it gets emulated with a structure (if necessary). */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Int64
+ *
+ * A typedef for a 64bit signed integer type. The size depends on the
+ * configuration. Only defined if there is real 64bit support;
+ * otherwise, it gets emulated with a structure (if necessary).
+ */
typedef signed XXX FT_Int64;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_UInt64 */
- /* */
- /* A typedef for a 64bit unsigned integer type. The size depends on */
- /* the configuration. Only defined if there is real 64bit support; */
- /* otherwise, it gets emulated with a structure (if necessary). */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_UInt64
+ *
+ * A typedef for a 64bit unsigned integer type. The size depends on the
+ * configuration. Only defined if there is real 64bit support;
+ * otherwise, it gets emulated with a structure (if necessary).
+ */
typedef unsigned XXX FT_UInt64;
/* */
@@ -251,7 +250,7 @@ FT_BEGIN_HEADER
#endif
- /* look up an integer type that is at least 32 bits */
+ /* look up an integer type that is at least 32~bits */
#if FT_SIZEOF_INT >= ( 32 / FT_CHAR_BIT )
typedef int FT_Fast;
@@ -265,22 +264,22 @@ FT_BEGIN_HEADER
#endif
- /* determine whether we have a 64-bit int type for platforms without */
- /* Autoconf */
+ /* determine whether we have a 64-bit `int` type for platforms without */
+ /* Autoconf */
#if FT_SIZEOF_LONG == ( 64 / FT_CHAR_BIT )
- /* FT_LONG64 must be defined if a 64-bit type is available */
+ /* `FT_LONG64` must be defined if a 64-bit type is available */
#define FT_LONG64
#define FT_INT64 long
#define FT_UINT64 unsigned long
- /*************************************************************************/
- /* */
- /* A 64-bit data type may create compilation problems if you compile */
- /* in strict ANSI mode. To avoid them, we disable other 64-bit data */
- /* types if __STDC__ is defined. You can however ignore this rule */
- /* by defining the FT_CONFIG_OPTION_FORCE_INT64 configuration macro. */
- /* */
+ /**************************************************************************
+ *
+ * A 64-bit data type may create compilation problems if you compile in
+ * strict ANSI mode. To avoid them, we disable other 64-bit data types if
+ * `__STDC__` is defined. You can however ignore this rule by defining the
+ * `FT_CONFIG_OPTION_FORCE_INT64` configuration macro.
+ */
#elif !defined( __STDC__ ) || defined( FT_CONFIG_OPTION_FORCE_INT64 )
#if defined( __STDC_VERSION__ ) && __STDC_VERSION__ >= 199901L
@@ -289,19 +288,19 @@ FT_BEGIN_HEADER
#define FT_INT64 long long int
#define FT_UINT64 unsigned long long int
-#elif defined( _MSC_VER ) && _MSC_VER >= 900 /* Visual C++ (and Intel C++) */
+#elif defined( _MSC_VER ) && _MSC_VER >= 900 /* Visual C++ (and Intel C++) */
- /* this compiler provides the __int64 type */
+ /* this compiler provides the `__int64` type */
#define FT_LONG64
#define FT_INT64 __int64
#define FT_UINT64 unsigned __int64
#elif defined( __BORLANDC__ ) /* Borland C++ */
- /* XXXX: We should probably check the value of __BORLANDC__ in order */
- /* to test the compiler version. */
+ /* XXXX: We should probably check the value of `__BORLANDC__` in order */
+ /* to test the compiler version. */
- /* this compiler provides the __int64 type */
+ /* this compiler provides the `__int64` type */
#define FT_LONG64
#define FT_INT64 __int64
#define FT_UINT64 unsigned __int64
@@ -318,7 +317,7 @@ FT_BEGIN_HEADER
#elif defined( __GNUC__ )
- /* GCC provides the `long long' type */
+ /* GCC provides the `long long` type */
#define FT_LONG64
#define FT_INT64 long long int
#define FT_UINT64 unsigned long long int
@@ -342,11 +341,11 @@ FT_BEGIN_HEADER
#endif
- /*************************************************************************/
- /* */
- /* miscellaneous */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * miscellaneous
+ *
+ */
#define FT_BEGIN_STMNT do {
@@ -354,7 +353,7 @@ FT_BEGIN_HEADER
#define FT_DUMMY_STMNT FT_BEGIN_STMNT FT_END_STMNT
- /* typeof condition taken from gnulib's `intprops.h' header file */
+ /* `typeof` condition taken from gnulib's `intprops.h` header file */
#if ( ( defined( __GNUC__ ) && __GNUC__ >= 2 ) || \
( defined( __IBMC__ ) && __IBMC__ >= 1210 && \
defined( __IBM__TYPEOF__ ) ) || \
@@ -365,14 +364,14 @@ FT_BEGIN_HEADER
#endif
- /* Use FT_LOCAL and FT_LOCAL_DEF to declare and define, respectively, */
- /* a function that gets used only within the scope of a module. */
- /* Normally, both the header and source code files for such a */
- /* function are within a single module directory. */
- /* */
- /* Intra-module arrays should be tagged with FT_LOCAL_ARRAY and */
- /* FT_LOCAL_ARRAY_DEF. */
- /* */
+ /* Use `FT_LOCAL` and `FT_LOCAL_DEF` to declare and define, */
+ /* respectively, a function that gets used only within the scope of a */
+ /* module. Normally, both the header and source code files for such a */
+ /* function are within a single module directory. */
+ /* */
+ /* Intra-module arrays should be tagged with `FT_LOCAL_ARRAY` and */
+ /* `FT_LOCAL_ARRAY_DEF`. */
+ /* */
#ifdef FT_MAKE_OPTION_SINGLE_OBJECT
#define FT_LOCAL( x ) static x
@@ -394,12 +393,12 @@ FT_BEGIN_HEADER
#define FT_LOCAL_ARRAY_DEF( x ) const x
- /* Use FT_BASE and FT_BASE_DEF to declare and define, respectively, */
- /* functions that are used in more than a single module. In the */
- /* current setup this implies that the declaration is in a header */
- /* file in the `include/freetype/internal' directory, and the */
- /* function body is in a file in `src/base'. */
- /* */
+ /* Use `FT_BASE` and `FT_BASE_DEF` to declare and define, respectively, */
+ /* functions that are used in more than a single module. In the */
+ /* current setup this implies that the declaration is in a header file */
+ /* in the `include/freetype/internal` directory, and the function body */
+ /* is in a file in `src/base`. */
+ /* */
#ifndef FT_BASE
#ifdef __cplusplus
@@ -422,45 +421,50 @@ FT_BEGIN_HEADER
#endif /* !FT_BASE_DEF */
- /* When compiling FreeType as a DLL or DSO with hidden visibility */
- /* some systems/compilers need a special attribute in front OR after */
- /* the return type of function declarations. */
- /* */
- /* Two macros are used within the FreeType source code to define */
- /* exported library functions: FT_EXPORT and FT_EXPORT_DEF. */
- /* */
- /* FT_EXPORT( return_type ) */
- /* */
- /* is used in a function declaration, as in */
- /* */
- /* FT_EXPORT( FT_Error ) */
- /* FT_Init_FreeType( FT_Library* alibrary ); */
- /* */
- /* */
- /* FT_EXPORT_DEF( return_type ) */
- /* */
- /* is used in a function definition, as in */
- /* */
- /* FT_EXPORT_DEF( FT_Error ) */
- /* FT_Init_FreeType( FT_Library* alibrary ) */
- /* { */
- /* ... some code ... */
- /* return FT_Err_Ok; */
- /* } */
- /* */
- /* You can provide your own implementation of FT_EXPORT and */
- /* FT_EXPORT_DEF here if you want. */
- /* */
- /* To export a variable, use FT_EXPORT_VAR. */
- /* */
+ /* When compiling FreeType as a DLL or DSO with hidden visibility */
+ /* some systems/compilers need a special attribute in front OR after */
+ /* the return type of function declarations. */
+ /* */
+ /* Two macros are used within the FreeType source code to define */
+ /* exported library functions: `FT_EXPORT` and `FT_EXPORT_DEF`. */
+ /* */
+ /* - `FT_EXPORT( return_type )` */
+ /* */
+ /* is used in a function declaration, as in */
+ /* */
+ /* ``` */
+ /* FT_EXPORT( FT_Error ) */
+ /* FT_Init_FreeType( FT_Library* alibrary ); */
+ /* ``` */
+ /* */
+ /* - `FT_EXPORT_DEF( return_type )` */
+ /* */
+ /* is used in a function definition, as in */
+ /* */
+ /* ``` */
+ /* FT_EXPORT_DEF( FT_Error ) */
+ /* FT_Init_FreeType( FT_Library* alibrary ) */
+ /* { */
+ /* ... some code ... */
+ /* return FT_Err_Ok; */
+ /* } */
+ /* ``` */
+ /* */
+ /* You can provide your own implementation of `FT_EXPORT` and */
+ /* `FT_EXPORT_DEF` here if you want. */
+ /* */
+ /* To export a variable, use `FT_EXPORT_VAR`. */
+ /* */
#ifndef FT_EXPORT
#ifdef FT2_BUILD_LIBRARY
-#if defined( _WIN32 ) && ( defined( _DLL ) || defined( DLL_EXPORT ) )
+#if defined( _WIN32 ) && defined( DLL_EXPORT )
#define FT_EXPORT( x ) __declspec( dllexport ) x
#elif defined( __GNUC__ ) && __GNUC__ >= 4
#define FT_EXPORT( x ) __attribute__(( visibility( "default" ) )) x
+#elif defined( __SUNPRO_C ) && __SUNPRO_C >= 0x550
+#define FT_EXPORT( x ) __global x
#elif defined( __cplusplus )
#define FT_EXPORT( x ) extern "C" x
#else
@@ -469,7 +473,7 @@ FT_BEGIN_HEADER
#else
-#if defined( FT2_DLLIMPORT )
+#if defined( _WIN32 ) && defined( DLL_IMPORT )
#define FT_EXPORT( x ) __declspec( dllimport ) x
#elif defined( __cplusplus )
#define FT_EXPORT( x ) extern "C" x
@@ -508,7 +512,7 @@ FT_BEGIN_HEADER
/* C++ compiler and with 16bit compilers. */
/* */
- /* This is special. Within C++, you must specify `extern "C"' for */
+ /* This is special. Within C++, you must specify `extern "C"` for */
/* functions which are used via function pointers, and you also */
/* must do that for structures which contain function pointers to */
/* assure C linkage -- it's not possible to have (local) anonymous */
@@ -531,7 +535,7 @@ FT_BEGIN_HEADER
/* */
/* */
/* Some 16bit compilers have to redefine these macros to insert */
- /* the infamous `_cdecl' or `__fastcall' declarations. */
+ /* the infamous `_cdecl` or `__fastcall` declarations. */
/* */
#ifndef FT_CALLBACK_DEF
#ifdef __cplusplus
diff --git a/src/3rdparty/freetype/include/freetype/config/ftheader.h b/src/3rdparty/freetype/include/freetype/config/ftheader.h
index 702f77cc42..696d6ba906 100644
--- a/src/3rdparty/freetype/include/freetype/config/ftheader.h
+++ b/src/3rdparty/freetype/include/freetype/config/ftheader.h
@@ -1,19 +1,19 @@
-/***************************************************************************/
-/* */
-/* ftheader.h */
-/* */
-/* Build macros of the FreeType 2 library. */
-/* */
-/* Copyright 1996-2018 by */
-/* David Turner, Robert Wilhelm, and Werner Lemberg. */
-/* */
-/* This file is part of the FreeType project, and may only be used, */
-/* modified, and distributed under the terms of the FreeType project */
-/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
-/* this file you indicate that you have read the license and */
-/* understand and accept it fully. */
-/* */
-/***************************************************************************/
+/****************************************************************************
+ *
+ * ftheader.h
+ *
+ * Build macros of the FreeType 2 library.
+ *
+ * Copyright (C) 1996-2019 by
+ * David Turner, Robert Wilhelm, and Werner Lemberg.
+ *
+ * This file is part of the FreeType project, and may only be used,
+ * modified, and distributed under the terms of the FreeType project
+ * license, LICENSE.TXT. By continuing to use, modify, or distribute
+ * this file you indicate that you have read the license and
+ * understand and accept it fully.
+ *
+ */
#ifndef FTHEADER_H_
#define FTHEADER_H_
@@ -27,7 +27,7 @@
/* <Description> */
/* This macro is used in association with @FT_END_HEADER in header */
/* files to ensure that the declarations within are properly */
- /* encapsulated in an `extern "C" { .. }' block when included from a */
+ /* encapsulated in an `extern "C" { .. }` block when included from a */
/* C++ compiler. */
/* */
#ifdef __cplusplus
@@ -45,7 +45,7 @@
/* <Description> */
/* This macro is used in association with @FT_BEGIN_HEADER in header */
/* files to ensure that the declarations within are properly */
- /* encapsulated in an `extern "C" { .. }' block when included from a */
+ /* encapsulated in an `extern "C" { .. }` block when included from a */
/* C++ compiler. */
/* */
#ifdef __cplusplus
@@ -55,54 +55,54 @@
#endif
- /*************************************************************************/
- /* */
- /* Aliases for the FreeType 2 public and configuration files. */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * Aliases for the FreeType 2 public and configuration files.
+ *
+ */
- /*************************************************************************/
- /* */
- /* <Section> */
- /* header_file_macros */
- /* */
- /* <Title> */
- /* Header File Macros */
- /* */
- /* <Abstract> */
- /* Macro definitions used to #include specific header files. */
- /* */
- /* <Description> */
- /* The following macros are defined to the name of specific */
- /* FreeType~2 header files. They can be used directly in #include */
- /* statements as in: */
- /* */
- /* { */
- /* #include FT_FREETYPE_H */
- /* #include FT_MULTIPLE_MASTERS_H */
- /* #include FT_GLYPH_H */
- /* } */
- /* */
- /* There are several reasons why we are now using macros to name */
- /* public header files. The first one is that such macros are not */
- /* limited to the infamous 8.3~naming rule required by DOS (and */
- /* `FT_MULTIPLE_MASTERS_H' is a lot more meaningful than `ftmm.h'). */
- /* */
- /* The second reason is that it allows for more flexibility in the */
- /* way FreeType~2 is installed on a given system. */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * header_file_macros
+ *
+ * @title:
+ * Header File Macros
+ *
+ * @abstract:
+ * Macro definitions used to `#include` specific header files.
+ *
+ * @description:
+ * The following macros are defined to the name of specific FreeType~2
+ * header files. They can be used directly in `#include` statements as
+ * in:
+ *
+ * ```
+ * #include FT_FREETYPE_H
+ * #include FT_MULTIPLE_MASTERS_H
+ * #include FT_GLYPH_H
+ * ```
+ *
+ * There are several reasons why we are now using macros to name public
+ * header files. The first one is that such macros are not limited to
+ * the infamous 8.3~naming rule required by DOS (and
+ * `FT_MULTIPLE_MASTERS_H` is a lot more meaningful than `ftmm.h`).
+ *
+ * The second reason is that it allows for more flexibility in the way
+ * FreeType~2 is installed on a given system.
+ *
+ */
/* configuration files */
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_CONFIG_CONFIG_H
*
* @description:
- * A macro used in #include statements to name the file containing
+ * A macro used in `#include` statements to name the file containing
* FreeType~2 configuration data.
*
*/
@@ -111,13 +111,13 @@
#endif
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_CONFIG_STANDARD_LIBRARY_H
*
* @description:
- * A macro used in #include statements to name the file containing
+ * A macro used in `#include` statements to name the file containing
* FreeType~2 interface to the standard C library functions.
*
*/
@@ -126,13 +126,13 @@
#endif
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_CONFIG_OPTIONS_H
*
* @description:
- * A macro used in #include statements to name the file containing
+ * A macro used in `#include` statements to name the file containing
* FreeType~2 project-specific configuration options.
*
*/
@@ -141,13 +141,13 @@
#endif
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_CONFIG_MODULES_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* list of FreeType~2 modules that are statically linked to new library
* instances in @FT_Init_FreeType.
*
@@ -160,26 +160,26 @@
/* public headers */
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_FREETYPE_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* base FreeType~2 API.
*
*/
#define FT_FREETYPE_H <freetype/freetype.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_ERRORS_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* list of FreeType~2 error codes (and messages).
*
* It is included by @FT_FREETYPE_H.
@@ -188,26 +188,26 @@
#define FT_ERRORS_H <freetype/fterrors.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_MODULE_ERRORS_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* list of FreeType~2 module error offsets (and messages).
*
*/
#define FT_MODULE_ERRORS_H <freetype/ftmoderr.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_SYSTEM_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 interface to low-level operations (i.e., memory management
* and stream i/o).
*
@@ -217,13 +217,13 @@
#define FT_SYSTEM_H <freetype/ftsystem.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_IMAGE_H
*
* @description:
- * A macro used in #include statements to name the file containing type
+ * A macro used in `#include` statements to name the file containing type
* definitions related to glyph images (i.e., bitmaps, outlines,
* scan-converter parameters).
*
@@ -233,13 +233,13 @@
#define FT_IMAGE_H <freetype/ftimage.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_TYPES_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* basic data types defined by FreeType~2.
*
* It is included by @FT_FREETYPE_H.
@@ -248,13 +248,13 @@
#define FT_TYPES_H <freetype/fttypes.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_LIST_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* list management API of FreeType~2.
*
* (Most applications will never need to include this file.)
@@ -263,151 +263,151 @@
#define FT_LIST_H <freetype/ftlist.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_OUTLINE_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* scalable outline management API of FreeType~2.
*
*/
#define FT_OUTLINE_H <freetype/ftoutln.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_SIZES_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* API which manages multiple @FT_Size objects per face.
*
*/
#define FT_SIZES_H <freetype/ftsizes.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_MODULE_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* module management API of FreeType~2.
*
*/
#define FT_MODULE_H <freetype/ftmodapi.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_RENDER_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* renderer module management API of FreeType~2.
*
*/
#define FT_RENDER_H <freetype/ftrender.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_DRIVER_H
*
* @description:
- * A macro used in #include statements to name the file containing
+ * A macro used in `#include` statements to name the file containing
* structures and macros related to the driver modules.
*
*/
#define FT_DRIVER_H <freetype/ftdriver.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_AUTOHINTER_H
*
* @description:
- * A macro used in #include statements to name the file containing
+ * A macro used in `#include` statements to name the file containing
* structures and macros related to the auto-hinting module.
*
- * Deprecated since version 2.9; use @FT_DRIVER_H instead.
+ * Deprecated since version~2.9; use @FT_DRIVER_H instead.
*
*/
#define FT_AUTOHINTER_H FT_DRIVER_H
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_CFF_DRIVER_H
*
* @description:
- * A macro used in #include statements to name the file containing
+ * A macro used in `#include` statements to name the file containing
* structures and macros related to the CFF driver module.
*
- * Deprecated since version 2.9; use @FT_DRIVER_H instead.
+ * Deprecated since version~2.9; use @FT_DRIVER_H instead.
*
*/
#define FT_CFF_DRIVER_H FT_DRIVER_H
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_TRUETYPE_DRIVER_H
*
* @description:
- * A macro used in #include statements to name the file containing
+ * A macro used in `#include` statements to name the file containing
* structures and macros related to the TrueType driver module.
*
- * Deprecated since version 2.9; use @FT_DRIVER_H instead.
+ * Deprecated since version~2.9; use @FT_DRIVER_H instead.
*
*/
#define FT_TRUETYPE_DRIVER_H FT_DRIVER_H
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_PCF_DRIVER_H
*
* @description:
- * A macro used in #include statements to name the file containing
+ * A macro used in `#include` statements to name the file containing
* structures and macros related to the PCF driver module.
*
- * Deprecated since version 2.9; use @FT_DRIVER_H instead.
+ * Deprecated since version~2.9; use @FT_DRIVER_H instead.
*
*/
#define FT_PCF_DRIVER_H FT_DRIVER_H
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_TYPE1_TABLES_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* types and API specific to the Type~1 format.
*
*/
#define FT_TYPE1_TABLES_H <freetype/t1tables.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_TRUETYPE_IDS_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* enumeration values which identify name strings, languages, encodings,
* etc. This file really contains a _large_ set of constant macro
* definitions, taken from the TrueType and OpenType specifications.
@@ -416,174 +416,172 @@
#define FT_TRUETYPE_IDS_H <freetype/ttnameid.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_TRUETYPE_TABLES_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* types and API specific to the TrueType (as well as OpenType) format.
*
*/
#define FT_TRUETYPE_TABLES_H <freetype/tttables.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_TRUETYPE_TAGS_H
*
* @description:
- * A macro used in #include statements to name the file containing the
- * definitions of TrueType four-byte `tags' which identify blocks in
+ * A macro used in `#include` statements to name the file containing the
+ * definitions of TrueType four-byte 'tags' which identify blocks in
* SFNT-based font formats (i.e., TrueType and OpenType).
*
*/
#define FT_TRUETYPE_TAGS_H <freetype/tttags.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_BDF_H
*
* @description:
- * A macro used in #include statements to name the file containing the
- * definitions of an API which accesses BDF-specific strings from a
- * face.
+ * A macro used in `#include` statements to name the file containing the
+ * definitions of an API which accesses BDF-specific strings from a face.
*
*/
#define FT_BDF_H <freetype/ftbdf.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_CID_H
*
* @description:
- * A macro used in #include statements to name the file containing the
- * definitions of an API which access CID font information from a
- * face.
+ * A macro used in `#include` statements to name the file containing the
+ * definitions of an API which access CID font information from a face.
*
*/
#define FT_CID_H <freetype/ftcid.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_GZIP_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* definitions of an API which supports gzip-compressed files.
*
*/
#define FT_GZIP_H <freetype/ftgzip.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_LZW_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* definitions of an API which supports LZW-compressed files.
*
*/
#define FT_LZW_H <freetype/ftlzw.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_BZIP2_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* definitions of an API which supports bzip2-compressed files.
*
*/
#define FT_BZIP2_H <freetype/ftbzip2.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_WINFONTS_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* definitions of an API which supports Windows FNT files.
*
*/
#define FT_WINFONTS_H <freetype/ftwinfnt.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_GLYPH_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* API of the optional glyph management component.
*
*/
#define FT_GLYPH_H <freetype/ftglyph.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_BITMAP_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* API of the optional bitmap conversion component.
*
*/
#define FT_BITMAP_H <freetype/ftbitmap.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_BBOX_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* API of the optional exact bounding box computation routines.
*
*/
#define FT_BBOX_H <freetype/ftbbox.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_CACHE_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* API of the optional FreeType~2 cache sub-system.
*
*/
#define FT_CACHE_H <freetype/ftcache.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_MAC_H
*
* @description:
- * A macro used in #include statements to name the file containing the
- * Macintosh-specific FreeType~2 API. The latter is used to access
- * fonts embedded in resource forks.
+ * A macro used in `#include` statements to name the file containing the
+ * Macintosh-specific FreeType~2 API. The latter is used to access fonts
+ * embedded in resource forks.
*
* This header file must be explicitly included by client applications
* compiled on the Mac (note that the base API still works though).
@@ -592,105 +590,105 @@
#define FT_MAC_H <freetype/ftmac.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_MULTIPLE_MASTERS_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* optional multiple-masters management API of FreeType~2.
*
*/
#define FT_MULTIPLE_MASTERS_H <freetype/ftmm.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_SFNT_NAMES_H
*
* @description:
- * A macro used in #include statements to name the file containing the
- * optional FreeType~2 API which accesses embedded `name' strings in
+ * A macro used in `#include` statements to name the file containing the
+ * optional FreeType~2 API which accesses embedded 'name' strings in
* SFNT-based font formats (i.e., TrueType and OpenType).
*
*/
#define FT_SFNT_NAMES_H <freetype/ftsnames.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_OPENTYPE_VALIDATE_H
*
* @description:
- * A macro used in #include statements to name the file containing the
- * optional FreeType~2 API which validates OpenType tables (BASE, GDEF,
- * GPOS, GSUB, JSTF).
+ * A macro used in `#include` statements to name the file containing the
+ * optional FreeType~2 API which validates OpenType tables ('BASE',
+ * 'GDEF', 'GPOS', 'GSUB', 'JSTF').
*
*/
#define FT_OPENTYPE_VALIDATE_H <freetype/ftotval.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_GX_VALIDATE_H
*
* @description:
- * A macro used in #include statements to name the file containing the
- * optional FreeType~2 API which validates TrueTypeGX/AAT tables (feat,
- * mort, morx, bsln, just, kern, opbd, trak, prop).
+ * A macro used in `#include` statements to name the file containing the
+ * optional FreeType~2 API which validates TrueTypeGX/AAT tables ('feat',
+ * 'mort', 'morx', 'bsln', 'just', 'kern', 'opbd', 'trak', 'prop').
*
*/
#define FT_GX_VALIDATE_H <freetype/ftgxval.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_PFR_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which accesses PFR-specific data.
*
*/
#define FT_PFR_H <freetype/ftpfr.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_STROKER_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which provides functions to stroke outline paths.
*/
#define FT_STROKER_H <freetype/ftstroke.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_SYNTHESIS_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which performs artificial obliquing and emboldening.
*/
#define FT_SYNTHESIS_H <freetype/ftsynth.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_FONT_FORMATS_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which provides functions specific to font formats.
*/
#define FT_FONT_FORMATS_H <freetype/ftfntfmt.h>
@@ -699,67 +697,79 @@
#define FT_XFREE86_H FT_FONT_FORMATS_H
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_TRIGONOMETRY_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which performs trigonometric computations (e.g.,
* cosines and arc tangents).
*/
#define FT_TRIGONOMETRY_H <freetype/fttrigon.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_LCD_FILTER_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which performs color filtering for subpixel rendering.
*/
#define FT_LCD_FILTER_H <freetype/ftlcdfil.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_INCREMENTAL_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which performs incremental glyph loading.
*/
#define FT_INCREMENTAL_H <freetype/ftincrem.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_GASP_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which returns entries from the TrueType GASP table.
*/
#define FT_GASP_H <freetype/ftgasp.h>
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
* FT_ADVANCES_H
*
* @description:
- * A macro used in #include statements to name the file containing the
+ * A macro used in `#include` statements to name the file containing the
* FreeType~2 API which returns individual and ranged glyph advances.
*/
#define FT_ADVANCES_H <freetype/ftadvanc.h>
+ /**************************************************************************
+ *
+ * @macro:
+ * FT_COLOR_H
+ *
+ * @description:
+ * A macro used in `#include` statements to name the file containing the
+ * FreeType~2 API which handles the OpenType 'CPAL' table.
+ */
+#define FT_COLOR_H <freetype/ftcolor.h>
+
+
/* */
/* These header files don't need to be included by the user. */
@@ -770,14 +780,14 @@
#define FT_UNPATENTED_HINTING_H <freetype/ftparams.h>
#define FT_TRUETYPE_UNPATENTED_H <freetype/ftparams.h>
- /* FT_CACHE_H is the only header file needed for the cache subsystem. */
+ /* `FT_CACHE_H` is the only header file needed for the cache subsystem. */
#define FT_CACHE_IMAGE_H FT_CACHE_H
#define FT_CACHE_SMALL_BITMAPS_H FT_CACHE_H
#define FT_CACHE_CHARMAP_H FT_CACHE_H
/* The internals of the cache sub-system are no longer exposed. We */
- /* default to FT_CACHE_H at the moment just in case, but we know of */
- /* no rogue client that uses them. */
+ /* default to `FT_CACHE_H` at the moment just in case, but we know */
+ /* of no rogue client that uses them. */
/* */
#define FT_CACHE_MANAGER_H FT_CACHE_H
#define FT_CACHE_INTERNAL_MRU_H FT_CACHE_H
@@ -789,8 +799,8 @@
/*
- * Include internal headers definitions from <internal/...>
- * only when building the library.
+ * Include internal headers definitions from `<internal/...>` only when
+ * building the library.
*/
#ifdef FT2_BUILD_LIBRARY
#define FT_INTERNAL_INTERNAL_H <freetype/internal/internal.h>
diff --git a/src/3rdparty/freetype/include/freetype/config/ftmodule.h b/src/3rdparty/freetype/include/freetype/config/ftmodule.h
index 76d271a74b..7c603e5327 100644
--- a/src/3rdparty/freetype/include/freetype/config/ftmodule.h
+++ b/src/3rdparty/freetype/include/freetype/config/ftmodule.h
@@ -1,12 +1,12 @@
/*
- * This file registers the FreeType modules compiled into the library.
+ * This file registers the FreeType modules compiled into the library.
*
- * If you use GNU make, this file IS NOT USED! Instead, it is created in
- * the objects directory (normally `<topdir>/objs/') based on information
- * from `<topdir>/modules.cfg'.
+ * If you use GNU make, this file IS NOT USED! Instead, it is created in
+ * the objects directory (normally `<topdir>/objs/`) based on information
+ * from `<topdir>/modules.cfg`.
*
- * Please read `docs/INSTALL.ANY' and `docs/CUSTOMIZE' how to compile
- * FreeType without GNU make.
+ * Please read `docs/INSTALL.ANY` and `docs/CUSTOMIZE` how to compile
+ * FreeType without GNU make.
*
*/
diff --git a/src/3rdparty/freetype/include/freetype/config/ftoption.h b/src/3rdparty/freetype/include/freetype/config/ftoption.h
index 4bcab2af5c..12f47a82e8 100644
--- a/src/3rdparty/freetype/include/freetype/config/ftoption.h
+++ b/src/3rdparty/freetype/include/freetype/config/ftoption.h
@@ -1,19 +1,19 @@
-/***************************************************************************/
-/* */
-/* ftoption.h */
-/* */
-/* User-selectable configuration macros (specification only). */
-/* */
-/* Copyright 1996-2018 by */
-/* David Turner, Robert Wilhelm, and Werner Lemberg. */
-/* */
-/* This file is part of the FreeType project, and may only be used, */
-/* modified, and distributed under the terms of the FreeType project */
-/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
-/* this file you indicate that you have read the license and */
-/* understand and accept it fully. */
-/* */
-/***************************************************************************/
+/****************************************************************************
+ *
+ * ftoption.h
+ *
+ * User-selectable configuration macros (specification only).
+ *
+ * Copyright (C) 1996-2019 by
+ * David Turner, Robert Wilhelm, and Werner Lemberg.
+ *
+ * This file is part of the FreeType project, and may only be used,
+ * modified, and distributed under the terms of the FreeType project
+ * license, LICENSE.TXT. By continuing to use, modify, or distribute
+ * this file you indicate that you have read the license and
+ * understand and accept it fully.
+ *
+ */
#ifndef FTOPTION_H_
@@ -25,45 +25,47 @@
FT_BEGIN_HEADER
- /*************************************************************************/
- /* */
- /* USER-SELECTABLE CONFIGURATION MACROS */
- /* */
- /* This file contains the default configuration macro definitions for */
- /* a standard build of the FreeType library. There are three ways to */
- /* use this file to build project-specific versions of the library: */
- /* */
- /* - You can modify this file by hand, but this is not recommended in */
- /* cases where you would like to build several versions of the */
- /* library from a single source directory. */
- /* */
- /* - You can put a copy of this file in your build directory, more */
- /* precisely in `$BUILD/freetype/config/ftoption.h', where `$BUILD' */
- /* is the name of a directory that is included _before_ the FreeType */
- /* include path during compilation. */
- /* */
- /* The default FreeType Makefiles and Jamfiles use the build */
- /* directory `builds/<system>' by default, but you can easily change */
- /* that for your own projects. */
- /* */
- /* - Copy the file <ft2build.h> to `$BUILD/ft2build.h' and modify it */
- /* slightly to pre-define the macro FT_CONFIG_OPTIONS_H used to */
- /* locate this file during the build. For example, */
- /* */
- /* #define FT_CONFIG_OPTIONS_H <myftoptions.h> */
- /* #include <freetype/config/ftheader.h> */
- /* */
- /* will use `$BUILD/myftoptions.h' instead of this file for macro */
- /* definitions. */
- /* */
- /* Note also that you can similarly pre-define the macro */
- /* FT_CONFIG_MODULES_H used to locate the file listing of the modules */
- /* that are statically linked to the library at compile time. By */
- /* default, this file is <freetype/config/ftmodule.h>. */
- /* */
- /* We highly recommend using the third method whenever possible. */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * USER-SELECTABLE CONFIGURATION MACROS
+ *
+ * This file contains the default configuration macro definitions for a
+ * standard build of the FreeType library. There are three ways to use
+ * this file to build project-specific versions of the library:
+ *
+ * - You can modify this file by hand, but this is not recommended in
+ * cases where you would like to build several versions of the library
+ * from a single source directory.
+ *
+ * - You can put a copy of this file in your build directory, more
+ * precisely in `$BUILD/freetype/config/ftoption.h`, where `$BUILD` is
+ * the name of a directory that is included _before_ the FreeType include
+ * path during compilation.
+ *
+ * The default FreeType Makefiles and Jamfiles use the build directory
+ * `builds/<system>` by default, but you can easily change that for your
+ * own projects.
+ *
+ * - Copy the file <ft2build.h> to `$BUILD/ft2build.h` and modify it
+ * slightly to pre-define the macro `FT_CONFIG_OPTIONS_H` used to locate
+ * this file during the build. For example,
+ *
+ * ```
+ * #define FT_CONFIG_OPTIONS_H <myftoptions.h>
+ * #include <freetype/config/ftheader.h>
+ * ```
+ *
+ * will use `$BUILD/myftoptions.h` instead of this file for macro
+ * definitions.
+ *
+ * Note also that you can similarly pre-define the macro
+ * `FT_CONFIG_MODULES_H` used to locate the file listing of the modules
+ * that are statically linked to the library at compile time. By
+ * default, this file is `<freetype/config/ftmodule.h>`.
+ *
+ * We highly recommend using the third method whenever possible.
+ *
+ */
/*************************************************************************/
@@ -75,444 +77,433 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*#***********************************************************************/
- /* */
- /* If you enable this configuration option, FreeType recognizes an */
- /* environment variable called `FREETYPE_PROPERTIES', which can be used */
- /* to control the various font drivers and modules. The controllable */
- /* properties are listed in the section @properties. */
- /* */
- /* You have to undefine this configuration option on platforms that lack */
- /* the concept of environment variables (and thus don't have the */
- /* `getenv' function), for example Windows CE. */
- /* */
- /* `FREETYPE_PROPERTIES' has the following syntax form (broken here into */
- /* multiple lines for better readability). */
- /* */
- /* { */
- /* <optional whitespace> */
- /* <module-name1> ':' */
- /* <property-name1> '=' <property-value1> */
- /* <whitespace> */
- /* <module-name2> ':' */
- /* <property-name2> '=' <property-value2> */
- /* ... */
- /* } */
- /* */
- /* Example: */
- /* */
- /* FREETYPE_PROPERTIES=truetype:interpreter-version=35 \ */
- /* cff:no-stem-darkening=1 \ */
- /* autofitter:warping=1 */
- /* */
+ /*#************************************************************************
+ *
+ * If you enable this configuration option, FreeType recognizes an
+ * environment variable called `FREETYPE_PROPERTIES`, which can be used to
+ * control the various font drivers and modules. The controllable
+ * properties are listed in the section @properties.
+ *
+ * You have to undefine this configuration option on platforms that lack
+ * the concept of environment variables (and thus don't have the `getenv`
+ * function), for example Windows CE.
+ *
+ * `FREETYPE_PROPERTIES` has the following syntax form (broken here into
+ * multiple lines for better readability).
+ *
+ * ```
+ * <optional whitespace>
+ * <module-name1> ':'
+ * <property-name1> '=' <property-value1>
+ * <whitespace>
+ * <module-name2> ':'
+ * <property-name2> '=' <property-value2>
+ * ...
+ * ```
+ *
+ * Example:
+ *
+ * ```
+ * FREETYPE_PROPERTIES=truetype:interpreter-version=35 \
+ * cff:no-stem-darkening=1 \
+ * autofitter:warping=1
+ * ```
+ *
+ */
#define FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES
- /*************************************************************************/
- /* */
- /* Uncomment the line below if you want to activate LCD rendering */
- /* technology similar to ClearType in this build of the library. This */
- /* technology triples the resolution in the direction color subpixels. */
- /* To mitigate color fringes inherent to this technology, you also need */
- /* to explicitly set up LCD filtering. */
- /* */
- /* Note that this feature is covered by several Microsoft patents */
- /* and should not be activated in any default build of the library. */
- /* When this macro is not defined, FreeType offers alternative LCD */
- /* rendering technology that produces excellent output without LCD */
- /* filtering. */
- /* */
+ /**************************************************************************
+ *
+ * Uncomment the line below if you want to activate LCD rendering
+ * technology similar to ClearType in this build of the library. This
+ * technology triples the resolution in the direction color subpixels. To
+ * mitigate color fringes inherent to this technology, you also need to
+ * explicitly set up LCD filtering.
+ *
+ * Note that this feature is covered by several Microsoft patents and
+ * should not be activated in any default build of the library. When this
+ * macro is not defined, FreeType offers alternative LCD rendering
+ * technology that produces excellent output without LCD filtering.
+ */
/* #define FT_CONFIG_OPTION_SUBPIXEL_RENDERING */
- /*************************************************************************/
- /* */
- /* Many compilers provide a non-ANSI 64-bit data type that can be used */
- /* by FreeType to speed up some computations. However, this will create */
- /* some problems when compiling the library in strict ANSI mode. */
- /* */
- /* For this reason, the use of 64-bit integers is normally disabled when */
- /* the __STDC__ macro is defined. You can however disable this by */
- /* defining the macro FT_CONFIG_OPTION_FORCE_INT64 here. */
- /* */
- /* For most compilers, this will only create compilation warnings when */
- /* building the library. */
- /* */
- /* ObNote: The compiler-specific 64-bit integers are detected in the */
- /* file `ftconfig.h' either statically or through the */
- /* `configure' script on supported platforms. */
- /* */
+ /**************************************************************************
+ *
+ * Many compilers provide a non-ANSI 64-bit data type that can be used by
+ * FreeType to speed up some computations. However, this will create some
+ * problems when compiling the library in strict ANSI mode.
+ *
+ * For this reason, the use of 64-bit integers is normally disabled when
+ * the `__STDC__` macro is defined. You can however disable this by
+ * defining the macro `FT_CONFIG_OPTION_FORCE_INT64` here.
+ *
+ * For most compilers, this will only create compilation warnings when
+ * building the library.
+ *
+ * ObNote: The compiler-specific 64-bit integers are detected in the
+ * file `ftconfig.h` either statically or through the `configure`
+ * script on supported platforms.
+ */
#undef FT_CONFIG_OPTION_FORCE_INT64
- /*************************************************************************/
- /* */
- /* If this macro is defined, do not try to use an assembler version of */
- /* performance-critical functions (e.g. FT_MulFix). You should only do */
- /* that to verify that the assembler function works properly, or to */
- /* execute benchmark tests of the various implementations. */
+ /**************************************************************************
+ *
+ * If this macro is defined, do not try to use an assembler version of
+ * performance-critical functions (e.g., @FT_MulFix). You should only do
+ * that to verify that the assembler function works properly, or to execute
+ * benchmark tests of the various implementations.
+ */
/* #define FT_CONFIG_OPTION_NO_ASSEMBLER */
- /*************************************************************************/
- /* */
- /* If this macro is defined, try to use an inlined assembler version of */
- /* the `FT_MulFix' function, which is a `hotspot' when loading and */
- /* hinting glyphs, and which should be executed as fast as possible. */
- /* */
- /* Note that if your compiler or CPU is not supported, this will default */
- /* to the standard and portable implementation found in `ftcalc.c'. */
- /* */
+ /**************************************************************************
+ *
+ * If this macro is defined, try to use an inlined assembler version of the
+ * @FT_MulFix function, which is a 'hotspot' when loading and hinting
+ * glyphs, and which should be executed as fast as possible.
+ *
+ * Note that if your compiler or CPU is not supported, this will default to
+ * the standard and portable implementation found in `ftcalc.c`.
+ */
#define FT_CONFIG_OPTION_INLINE_MULFIX
- /*************************************************************************/
- /* */
- /* LZW-compressed file support. */
- /* */
- /* FreeType now handles font files that have been compressed with the */
- /* `compress' program. This is mostly used to parse many of the PCF */
- /* files that come with various X11 distributions. The implementation */
- /* uses NetBSD's `zopen' to partially uncompress the file on the fly */
- /* (see src/lzw/ftgzip.c). */
- /* */
- /* Define this macro if you want to enable this `feature'. */
- /* */
+ /**************************************************************************
+ *
+ * LZW-compressed file support.
+ *
+ * FreeType now handles font files that have been compressed with the
+ * `compress` program. This is mostly used to parse many of the PCF
+ * files that come with various X11 distributions. The implementation
+ * uses NetBSD's `zopen` to partially uncompress the file on the fly (see
+ * `src/lzw/ftgzip.c`).
+ *
+ * Define this macro if you want to enable this 'feature'.
+ */
#define FT_CONFIG_OPTION_USE_LZW
- /*************************************************************************/
- /* */
- /* Gzip-compressed file support. */
- /* */
- /* FreeType now handles font files that have been compressed with the */
- /* `gzip' program. This is mostly used to parse many of the PCF files */
- /* that come with XFree86. The implementation uses `zlib' to */
- /* partially uncompress the file on the fly (see src/gzip/ftgzip.c). */
- /* */
- /* Define this macro if you want to enable this `feature'. See also */
- /* the macro FT_CONFIG_OPTION_SYSTEM_ZLIB below. */
- /* */
+ /**************************************************************************
+ *
+ * Gzip-compressed file support.
+ *
+ * FreeType now handles font files that have been compressed with the
+ * `gzip` program. This is mostly used to parse many of the PCF files
+ * that come with XFree86. The implementation uses 'zlib' to partially
+ * uncompress the file on the fly (see `src/gzip/ftgzip.c`).
+ *
+ * Define this macro if you want to enable this 'feature'. See also the
+ * macro `FT_CONFIG_OPTION_SYSTEM_ZLIB` below.
+ */
#define FT_CONFIG_OPTION_USE_ZLIB
- /*************************************************************************/
- /* */
- /* ZLib library selection */
- /* */
- /* This macro is only used when FT_CONFIG_OPTION_USE_ZLIB is defined. */
- /* It allows FreeType's `ftgzip' component to link to the system's */
- /* installation of the ZLib library. This is useful on systems like */
- /* Unix or VMS where it generally is already available. */
- /* */
- /* If you let it undefined, the component will use its own copy */
- /* of the zlib sources instead. These have been modified to be */
- /* included directly within the component and *not* export external */
- /* function names. This allows you to link any program with FreeType */
- /* _and_ ZLib without linking conflicts. */
- /* */
- /* Do not #undef this macro here since the build system might define */
- /* it for certain configurations only. */
- /* */
- /* If you use a build system like cmake or the `configure' script, */
- /* options set by those programs have precendence, overwriting the */
- /* value here with the configured one. */
- /* */
+ /**************************************************************************
+ *
+ * ZLib library selection
+ *
+ * This macro is only used when `FT_CONFIG_OPTION_USE_ZLIB` is defined.
+ * It allows FreeType's 'ftgzip' component to link to the system's
+ * installation of the ZLib library. This is useful on systems like
+ * Unix or VMS where it generally is already available.
+ *
+ * If you let it undefined, the component will use its own copy of the
+ * zlib sources instead. These have been modified to be included
+ * directly within the component and **not** export external function
+ * names. This allows you to link any program with FreeType _and_ ZLib
+ * without linking conflicts.
+ *
+ * Do not `#undef` this macro here since the build system might define
+ * it for certain configurations only.
+ *
+ * If you use a build system like cmake or the `configure` script,
+ * options set by those programs have precedence, overwriting the value
+ * here with the configured one.
+ */
/* #define FT_CONFIG_OPTION_SYSTEM_ZLIB */
- /*************************************************************************/
- /* */
- /* Bzip2-compressed file support. */
- /* */
- /* FreeType now handles font files that have been compressed with the */
- /* `bzip2' program. This is mostly used to parse many of the PCF */
- /* files that come with XFree86. The implementation uses `libbz2' to */
- /* partially uncompress the file on the fly (see src/bzip2/ftbzip2.c). */
- /* Contrary to gzip, bzip2 currently is not included and need to use */
- /* the system available bzip2 implementation. */
- /* */
- /* Define this macro if you want to enable this `feature'. */
- /* */
- /* If you use a build system like cmake or the `configure' script, */
- /* options set by those programs have precendence, overwriting the */
- /* value here with the configured one. */
- /* */
+ /**************************************************************************
+ *
+ * Bzip2-compressed file support.
+ *
+ * FreeType now handles font files that have been compressed with the
+ * `bzip2` program. This is mostly used to parse many of the PCF files
+ * that come with XFree86. The implementation uses `libbz2` to partially
+ * uncompress the file on the fly (see `src/bzip2/ftbzip2.c`). Contrary
+ * to gzip, bzip2 currently is not included and need to use the system
+ * available bzip2 implementation.
+ *
+ * Define this macro if you want to enable this 'feature'.
+ *
+ * If you use a build system like cmake or the `configure` script,
+ * options set by those programs have precedence, overwriting the value
+ * here with the configured one.
+ */
/* #define FT_CONFIG_OPTION_USE_BZIP2 */
- /*************************************************************************/
- /* */
- /* Define to disable the use of file stream functions and types, FILE, */
- /* fopen() etc. Enables the use of smaller system libraries on embedded */
- /* systems that have multiple system libraries, some with or without */
- /* file stream support, in the cases where file stream support is not */
- /* necessary such as memory loading of font files. */
- /* */
+ /**************************************************************************
+ *
+ * Define to disable the use of file stream functions and types, `FILE`,
+ * `fopen`, etc. Enables the use of smaller system libraries on embedded
+ * systems that have multiple system libraries, some with or without file
+ * stream support, in the cases where file stream support is not necessary
+ * such as memory loading of font files.
+ */
/* #define FT_CONFIG_OPTION_DISABLE_STREAM_SUPPORT */
- /*************************************************************************/
- /* */
- /* PNG bitmap support. */
- /* */
- /* FreeType now handles loading color bitmap glyphs in the PNG format. */
- /* This requires help from the external libpng library. Uncompressed */
- /* color bitmaps do not need any external libraries and will be */
- /* supported regardless of this configuration. */
- /* */
- /* Define this macro if you want to enable this `feature'. */
- /* */
- /* If you use a build system like cmake or the `configure' script, */
- /* options set by those programs have precendence, overwriting the */
- /* value here with the configured one. */
- /* */
+ /**************************************************************************
+ *
+ * PNG bitmap support.
+ *
+ * FreeType now handles loading color bitmap glyphs in the PNG format.
+ * This requires help from the external libpng library. Uncompressed
+ * color bitmaps do not need any external libraries and will be supported
+ * regardless of this configuration.
+ *
+ * Define this macro if you want to enable this 'feature'.
+ *
+ * If you use a build system like cmake or the `configure` script,
+ * options set by those programs have precedence, overwriting the value
+ * here with the configured one.
+ */
/* #define FT_CONFIG_OPTION_USE_PNG */
- /*************************************************************************/
- /* */
- /* HarfBuzz support. */
- /* */
- /* FreeType uses the HarfBuzz library to improve auto-hinting of */
- /* OpenType fonts. If available, many glyphs not directly addressable */
- /* by a font's character map will be hinted also. */
- /* */
- /* Define this macro if you want to enable this `feature'. */
- /* */
- /* If you use a build system like cmake or the `configure' script, */
- /* options set by those programs have precendence, overwriting the */
- /* value here with the configured one. */
- /* */
+ /**************************************************************************
+ *
+ * HarfBuzz support.
+ *
+ * FreeType uses the HarfBuzz library to improve auto-hinting of OpenType
+ * fonts. If available, many glyphs not directly addressable by a font's
+ * character map will be hinted also.
+ *
+ * Define this macro if you want to enable this 'feature'.
+ *
+ * If you use a build system like cmake or the `configure` script,
+ * options set by those programs have precedence, overwriting the value
+ * here with the configured one.
+ */
/* #define FT_CONFIG_OPTION_USE_HARFBUZZ */
- /*************************************************************************/
- /* */
- /* Glyph Postscript Names handling */
- /* */
- /* By default, FreeType 2 is compiled with the `psnames' module. This */
- /* module is in charge of converting a glyph name string into a */
- /* Unicode value, or return a Macintosh standard glyph name for the */
- /* use with the TrueType `post' table. */
- /* */
- /* Undefine this macro if you do not want `psnames' compiled in your */
- /* build of FreeType. This has the following effects: */
- /* */
- /* - The TrueType driver will provide its own set of glyph names, */
- /* if you build it to support postscript names in the TrueType */
- /* `post' table, but will not synthesize a missing Unicode charmap. */
- /* */
- /* - The Type 1 driver will not be able to synthesize a Unicode */
- /* charmap out of the glyphs found in the fonts. */
- /* */
- /* You would normally undefine this configuration macro when building */
- /* a version of FreeType that doesn't contain a Type 1 or CFF driver. */
- /* */
+ /**************************************************************************
+ *
+ * Glyph Postscript Names handling
+ *
+ * By default, FreeType 2 is compiled with the 'psnames' module. This
+ * module is in charge of converting a glyph name string into a Unicode
+ * value, or return a Macintosh standard glyph name for the use with the
+ * TrueType 'post' table.
+ *
+ * Undefine this macro if you do not want 'psnames' compiled in your
+ * build of FreeType. This has the following effects:
+ *
+ * - The TrueType driver will provide its own set of glyph names, if you
+ * build it to support postscript names in the TrueType 'post' table,
+ * but will not synthesize a missing Unicode charmap.
+ *
+ * - The Type~1 driver will not be able to synthesize a Unicode charmap
+ * out of the glyphs found in the fonts.
+ *
+ * You would normally undefine this configuration macro when building a
+ * version of FreeType that doesn't contain a Type~1 or CFF driver.
+ */
#define FT_CONFIG_OPTION_POSTSCRIPT_NAMES
- /*************************************************************************/
- /* */
- /* Postscript Names to Unicode Values support */
- /* */
- /* By default, FreeType 2 is built with the `PSNames' module compiled */
- /* in. Among other things, the module is used to convert a glyph name */
- /* into a Unicode value. This is especially useful in order to */
- /* synthesize on the fly a Unicode charmap from the CFF/Type 1 driver */
- /* through a big table named the `Adobe Glyph List' (AGL). */
- /* */
- /* Undefine this macro if you do not want the Adobe Glyph List */
- /* compiled in your `PSNames' module. The Type 1 driver will not be */
- /* able to synthesize a Unicode charmap out of the glyphs found in the */
- /* fonts. */
- /* */
+ /**************************************************************************
+ *
+ * Postscript Names to Unicode Values support
+ *
+ * By default, FreeType~2 is built with the 'psnames' module compiled in.
+ * Among other things, the module is used to convert a glyph name into a
+ * Unicode value. This is especially useful in order to synthesize on
+ * the fly a Unicode charmap from the CFF/Type~1 driver through a big
+ * table named the 'Adobe Glyph List' (AGL).
+ *
+ * Undefine this macro if you do not want the Adobe Glyph List compiled
+ * in your 'psnames' module. The Type~1 driver will not be able to
+ * synthesize a Unicode charmap out of the glyphs found in the fonts.
+ */
#define FT_CONFIG_OPTION_ADOBE_GLYPH_LIST
- /*************************************************************************/
- /* */
- /* Support for Mac fonts */
- /* */
- /* Define this macro if you want support for outline fonts in Mac */
- /* format (mac dfont, mac resource, macbinary containing a mac */
- /* resource) on non-Mac platforms. */
- /* */
- /* Note that the `FOND' resource isn't checked. */
- /* */
+ /**************************************************************************
+ *
+ * Support for Mac fonts
+ *
+ * Define this macro if you want support for outline fonts in Mac format
+ * (mac dfont, mac resource, macbinary containing a mac resource) on
+ * non-Mac platforms.
+ *
+ * Note that the 'FOND' resource isn't checked.
+ */
#define FT_CONFIG_OPTION_MAC_FONTS
- /*************************************************************************/
- /* */
- /* Guessing methods to access embedded resource forks */
- /* */
- /* Enable extra Mac fonts support on non-Mac platforms (e.g. */
- /* GNU/Linux). */
- /* */
- /* Resource forks which include fonts data are stored sometimes in */
- /* locations which users or developers don't expected. In some cases, */
- /* resource forks start with some offset from the head of a file. In */
- /* other cases, the actual resource fork is stored in file different */
- /* from what the user specifies. If this option is activated, */
- /* FreeType tries to guess whether such offsets or different file */
- /* names must be used. */
- /* */
- /* Note that normal, direct access of resource forks is controlled via */
- /* the FT_CONFIG_OPTION_MAC_FONTS option. */
- /* */
+ /**************************************************************************
+ *
+ * Guessing methods to access embedded resource forks
+ *
+ * Enable extra Mac fonts support on non-Mac platforms (e.g., GNU/Linux).
+ *
+ * Resource forks which include fonts data are stored sometimes in
+ * locations which users or developers don't expected. In some cases,
+ * resource forks start with some offset from the head of a file. In
+ * other cases, the actual resource fork is stored in file different from
+ * what the user specifies. If this option is activated, FreeType tries
+ * to guess whether such offsets or different file names must be used.
+ *
+ * Note that normal, direct access of resource forks is controlled via
+ * the `FT_CONFIG_OPTION_MAC_FONTS` option.
+ */
#ifdef FT_CONFIG_OPTION_MAC_FONTS
#define FT_CONFIG_OPTION_GUESSING_EMBEDDED_RFORK
#endif
- /*************************************************************************/
- /* */
- /* Allow the use of FT_Incremental_Interface to load typefaces that */
- /* contain no glyph data, but supply it via a callback function. */
- /* This is required by clients supporting document formats which */
- /* supply font data incrementally as the document is parsed, such */
- /* as the Ghostscript interpreter for the PostScript language. */
- /* */
+ /**************************************************************************
+ *
+ * Allow the use of `FT_Incremental_Interface` to load typefaces that
+ * contain no glyph data, but supply it via a callback function. This is
+ * required by clients supporting document formats which supply font data
+ * incrementally as the document is parsed, such as the Ghostscript
+ * interpreter for the PostScript language.
+ */
#define FT_CONFIG_OPTION_INCREMENTAL
- /*************************************************************************/
- /* */
- /* The size in bytes of the render pool used by the scan-line converter */
- /* to do all of its work. */
- /* */
+ /**************************************************************************
+ *
+ * The size in bytes of the render pool used by the scan-line converter to
+ * do all of its work.
+ */
#define FT_RENDER_POOL_SIZE 16384L
- /*************************************************************************/
- /* */
- /* FT_MAX_MODULES */
- /* */
- /* The maximum number of modules that can be registered in a single */
- /* FreeType library object. 32 is the default. */
- /* */
+ /**************************************************************************
+ *
+ * FT_MAX_MODULES
+ *
+ * The maximum number of modules that can be registered in a single
+ * FreeType library object. 32~is the default.
+ */
#define FT_MAX_MODULES 32
- /*************************************************************************/
- /* */
- /* Debug level */
- /* */
- /* FreeType can be compiled in debug or trace mode. In debug mode, */
- /* errors are reported through the `ftdebug' component. In trace */
- /* mode, additional messages are sent to the standard output during */
- /* execution. */
- /* */
- /* Define FT_DEBUG_LEVEL_ERROR to build the library in debug mode. */
- /* Define FT_DEBUG_LEVEL_TRACE to build it in trace mode. */
- /* */
- /* Don't define any of these macros to compile in `release' mode! */
- /* */
- /* Do not #undef these macros here since the build system might define */
- /* them for certain configurations only. */
- /* */
+ /**************************************************************************
+ *
+ * Debug level
+ *
+ * FreeType can be compiled in debug or trace mode. In debug mode,
+ * errors are reported through the 'ftdebug' component. In trace mode,
+ * additional messages are sent to the standard output during execution.
+ *
+ * Define `FT_DEBUG_LEVEL_ERROR` to build the library in debug mode.
+ * Define `FT_DEBUG_LEVEL_TRACE` to build it in trace mode.
+ *
+ * Don't define any of these macros to compile in 'release' mode!
+ *
+ * Do not `#undef` these macros here since the build system might define
+ * them for certain configurations only.
+ */
/* #define FT_DEBUG_LEVEL_ERROR */
/* #define FT_DEBUG_LEVEL_TRACE */
- /*************************************************************************/
- /* */
- /* Autofitter debugging */
- /* */
- /* If FT_DEBUG_AUTOFIT is defined, FreeType provides some means to */
- /* control the autofitter behaviour for debugging purposes with global */
- /* boolean variables (consequently, you should *never* enable this */
- /* while compiling in `release' mode): */
- /* */
- /* _af_debug_disable_horz_hints */
- /* _af_debug_disable_vert_hints */
- /* _af_debug_disable_blue_hints */
- /* */
- /* Additionally, the following functions provide dumps of various */
- /* internal autofit structures to stdout (using `printf'): */
- /* */
- /* af_glyph_hints_dump_points */
- /* af_glyph_hints_dump_segments */
- /* af_glyph_hints_dump_edges */
- /* af_glyph_hints_get_num_segments */
- /* af_glyph_hints_get_segment_offset */
- /* */
- /* As an argument, they use another global variable: */
- /* */
- /* _af_debug_hints */
- /* */
- /* Please have a look at the `ftgrid' demo program to see how those */
- /* variables and macros should be used. */
- /* */
- /* Do not #undef these macros here since the build system might define */
- /* them for certain configurations only. */
- /* */
+ /**************************************************************************
+ *
+ * Autofitter debugging
+ *
+ * If `FT_DEBUG_AUTOFIT` is defined, FreeType provides some means to
+ * control the autofitter behaviour for debugging purposes with global
+ * boolean variables (consequently, you should **never** enable this
+ * while compiling in 'release' mode):
+ *
+ * ```
+ * _af_debug_disable_horz_hints
+ * _af_debug_disable_vert_hints
+ * _af_debug_disable_blue_hints
+ * ```
+ *
+ * Additionally, the following functions provide dumps of various
+ * internal autofit structures to stdout (using `printf`):
+ *
+ * ```
+ * af_glyph_hints_dump_points
+ * af_glyph_hints_dump_segments
+ * af_glyph_hints_dump_edges
+ * af_glyph_hints_get_num_segments
+ * af_glyph_hints_get_segment_offset
+ * ```
+ *
+ * As an argument, they use another global variable:
+ *
+ * ```
+ * _af_debug_hints
+ * ```
+ *
+ * Please have a look at the `ftgrid` demo program to see how those
+ * variables and macros should be used.
+ *
+ * Do not `#undef` these macros here since the build system might define
+ * them for certain configurations only.
+ */
/* #define FT_DEBUG_AUTOFIT */
- /*************************************************************************/
- /* */
- /* Memory Debugging */
- /* */
- /* FreeType now comes with an integrated memory debugger that is */
- /* capable of detecting simple errors like memory leaks or double */
- /* deletes. To compile it within your build of the library, you */
- /* should define FT_DEBUG_MEMORY here. */
- /* */
- /* Note that the memory debugger is only activated at runtime when */
- /* when the _environment_ variable `FT2_DEBUG_MEMORY' is defined also! */
- /* */
- /* Do not #undef this macro here since the build system might define */
- /* it for certain configurations only. */
- /* */
+ /**************************************************************************
+ *
+ * Memory Debugging
+ *
+ * FreeType now comes with an integrated memory debugger that is capable
+ * of detecting simple errors like memory leaks or double deletes. To
+ * compile it within your build of the library, you should define
+ * `FT_DEBUG_MEMORY` here.
+ *
+ * Note that the memory debugger is only activated at runtime when when
+ * the _environment_ variable `FT2_DEBUG_MEMORY` is defined also!
+ *
+ * Do not `#undef` this macro here since the build system might define it
+ * for certain configurations only.
+ */
/* #define FT_DEBUG_MEMORY */
- /*************************************************************************/
- /* */
- /* Module errors */
- /* */
- /* If this macro is set (which is _not_ the default), the higher byte */
- /* of an error code gives the module in which the error has occurred, */
- /* while the lower byte is the real error code. */
- /* */
- /* Setting this macro makes sense for debugging purposes only, since */
- /* it would break source compatibility of certain programs that use */
- /* FreeType 2. */
- /* */
- /* More details can be found in the files ftmoderr.h and fterrors.h. */
- /* */
+ /**************************************************************************
+ *
+ * Module errors
+ *
+ * If this macro is set (which is _not_ the default), the higher byte of
+ * an error code gives the module in which the error has occurred, while
+ * the lower byte is the real error code.
+ *
+ * Setting this macro makes sense for debugging purposes only, since it
+ * would break source compatibility of certain programs that use
+ * FreeType~2.
+ *
+ * More details can be found in the files `ftmoderr.h` and `fterrors.h`.
+ */
#undef FT_CONFIG_OPTION_USE_MODULE_ERRORS
- /*************************************************************************/
- /* */
- /* Position Independent Code */
- /* */
- /* If this macro is set (which is _not_ the default), FreeType2 will */
- /* avoid creating constants that require address fixups. Instead the */
- /* constants will be moved into a struct and additional intialization */
- /* code will be used. */
- /* */
- /* Setting this macro is needed for systems that prohibit address */
- /* fixups, such as BREW. [Note that standard compilers like gcc or */
- /* clang handle PIC generation automatically; you don't have to set */
- /* FT_CONFIG_OPTION_PIC, which is only necessary for very special */
- /* compilers.] */
- /* */
- /* Note that FT_CONFIG_OPTION_PIC support is not available for all */
- /* modules (see `modules.cfg' for a complete list). For building with */
- /* FT_CONFIG_OPTION_PIC support, do the following. */
- /* */
- /* 0. Clone the repository. */
- /* 1. Define FT_CONFIG_OPTION_PIC. */
- /* 2. Remove all subdirectories in `src' that don't have */
- /* FT_CONFIG_OPTION_PIC support. */
- /* 3. Comment out the corresponding modules in `modules.cfg'. */
- /* 4. Compile. */
- /* */
-/* #define FT_CONFIG_OPTION_PIC */
+ /**************************************************************************
+ *
+ * Error Strings
+ *
+ * If this macro is set, `FT_Error_String` will return meaningful
+ * descriptions. This is not enabled by default to reduce the overall
+ * size of FreeType.
+ *
+ * More details can be found in the file `fterrors.h`.
+ */
+/* #define FT_CONFIG_OPTION_ERROR_STRINGS */
/*************************************************************************/
@@ -524,50 +515,60 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* Define TT_CONFIG_OPTION_EMBEDDED_BITMAPS if you want to support */
- /* embedded bitmaps in all formats using the SFNT module (namely */
- /* TrueType & OpenType). */
- /* */
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_EMBEDDED_BITMAPS` if you want to support
+ * embedded bitmaps in all formats using the 'sfnt' module (namely
+ * TrueType~& OpenType).
+ */
#define TT_CONFIG_OPTION_EMBEDDED_BITMAPS
- /*************************************************************************/
- /* */
- /* Define TT_CONFIG_OPTION_POSTSCRIPT_NAMES if you want to be able to */
- /* load and enumerate the glyph Postscript names in a TrueType or */
- /* OpenType file. */
- /* */
- /* Note that when you do not compile the `PSNames' module by undefining */
- /* the above FT_CONFIG_OPTION_POSTSCRIPT_NAMES, the `sfnt' module will */
- /* contain additional code used to read the PS Names table from a font. */
- /* */
- /* (By default, the module uses `PSNames' to extract glyph names.) */
- /* */
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_COLOR_LAYERS` if you want to support coloured
+ * outlines (from the 'COLR'/'CPAL' tables) in all formats using the 'sfnt'
+ * module (namely TrueType~& OpenType).
+ */
+#define TT_CONFIG_OPTION_COLOR_LAYERS
+
+
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_POSTSCRIPT_NAMES` if you want to be able to
+ * load and enumerate the glyph Postscript names in a TrueType or OpenType
+ * file.
+ *
+ * Note that when you do not compile the 'psnames' module by undefining the
+ * above `FT_CONFIG_OPTION_POSTSCRIPT_NAMES`, the 'sfnt' module will
+ * contain additional code used to read the PS Names table from a font.
+ *
+ * (By default, the module uses 'psnames' to extract glyph names.)
+ */
#define TT_CONFIG_OPTION_POSTSCRIPT_NAMES
- /*************************************************************************/
- /* */
- /* Define TT_CONFIG_OPTION_SFNT_NAMES if your applications need to */
- /* access the internal name table in a SFNT-based format like TrueType */
- /* or OpenType. The name table contains various strings used to */
- /* describe the font, like family name, copyright, version, etc. It */
- /* does not contain any glyph name though. */
- /* */
- /* Accessing SFNT names is done through the functions declared in */
- /* `ftsnames.h'. */
- /* */
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_SFNT_NAMES` if your applications need to access
+ * the internal name table in a SFNT-based format like TrueType or
+ * OpenType. The name table contains various strings used to describe the
+ * font, like family name, copyright, version, etc. It does not contain
+ * any glyph name though.
+ *
+ * Accessing SFNT names is done through the functions declared in
+ * `ftsnames.h`.
+ */
#define TT_CONFIG_OPTION_SFNT_NAMES
- /*************************************************************************/
- /* */
- /* TrueType CMap support */
- /* */
- /* Here you can fine-tune which TrueType CMap table format shall be */
- /* supported. */
+ /**************************************************************************
+ *
+ * TrueType CMap support
+ *
+ * Here you can fine-tune which TrueType CMap table format shall be
+ * supported.
+ */
#define TT_CONFIG_CMAP_FORMAT_0
#define TT_CONFIG_CMAP_FORMAT_2
#define TT_CONFIG_CMAP_FORMAT_4
@@ -587,131 +588,130 @@ FT_BEGIN_HEADER
/*************************************************************************/
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* Define TT_CONFIG_OPTION_BYTECODE_INTERPRETER if you want to compile */
- /* a bytecode interpreter in the TrueType driver. */
- /* */
- /* By undefining this, you will only compile the code necessary to load */
- /* TrueType glyphs without hinting. */
- /* */
- /* Do not #undef this macro here, since the build system might */
- /* define it for certain configurations only. */
- /* */
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_BYTECODE_INTERPRETER` if you want to compile a
+ * bytecode interpreter in the TrueType driver.
+ *
+ * By undefining this, you will only compile the code necessary to load
+ * TrueType glyphs without hinting.
+ *
+ * Do not `#undef` this macro here, since the build system might define it
+ * for certain configurations only.
+ */
#define TT_CONFIG_OPTION_BYTECODE_INTERPRETER
- /*************************************************************************/
- /* */
- /* Define TT_CONFIG_OPTION_SUBPIXEL_HINTING if you want to compile */
- /* subpixel hinting support into the TrueType driver. This modifies the */
- /* TrueType hinting mechanism when anything but FT_RENDER_MODE_MONO is */
- /* requested. */
- /* */
- /* In particular, it modifies the bytecode interpreter to interpret (or */
- /* not) instructions in a certain way so that all TrueType fonts look */
- /* like they do in a Windows ClearType (DirectWrite) environment. See */
- /* [1] for a technical overview on what this means. See `ttinterp.h' */
- /* for more details on the LEAN option. */
- /* */
- /* There are three possible values. */
- /* */
- /* Value 1: */
- /* This value is associated with the `Infinality' moniker, */
- /* contributed by an individual nicknamed Infinality with the goal of */
- /* making TrueType fonts render better than on Windows. A high */
- /* amount of configurability and flexibility, down to rules for */
- /* single glyphs in fonts, but also very slow. Its experimental and */
- /* slow nature and the original developer losing interest meant that */
- /* this option was never enabled in default builds. */
- /* */
- /* The corresponding interpreter version is v38. */
- /* */
- /* Value 2: */
- /* The new default mode for the TrueType driver. The Infinality code */
- /* base was stripped to the bare minimum and all configurability */
- /* removed in the name of speed and simplicity. The configurability */
- /* was mainly aimed at legacy fonts like Arial, Times New Roman, or */
- /* Courier. Legacy fonts are fonts that modify vertical stems to */
- /* achieve clean black-and-white bitmaps. The new mode focuses on */
- /* applying a minimal set of rules to all fonts indiscriminately so */
- /* that modern and web fonts render well while legacy fonts render */
- /* okay. */
- /* */
- /* The corresponding interpreter version is v40. */
- /* */
- /* Value 3: */
- /* Compile both, making both v38 and v40 available (the latter is the */
- /* default). */
- /* */
- /* By undefining these, you get rendering behavior like on Windows */
- /* without ClearType, i.e., Windows XP without ClearType enabled and */
- /* Win9x (interpreter version v35). Or not, depending on how much */
- /* hinting blood and testing tears the font designer put into a given */
- /* font. If you define one or both subpixel hinting options, you can */
- /* switch between between v35 and the ones you define (using */
- /* `FT_Property_Set'). */
- /* */
- /* This option requires TT_CONFIG_OPTION_BYTECODE_INTERPRETER to be */
- /* defined. */
- /* */
- /* [1] https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx */
- /* */
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_SUBPIXEL_HINTING` if you want to compile
+ * subpixel hinting support into the TrueType driver. This modifies the
+ * TrueType hinting mechanism when anything but `FT_RENDER_MODE_MONO` is
+ * requested.
+ *
+ * In particular, it modifies the bytecode interpreter to interpret (or
+ * not) instructions in a certain way so that all TrueType fonts look like
+ * they do in a Windows ClearType (DirectWrite) environment. See [1] for a
+ * technical overview on what this means. See `ttinterp.h` for more
+ * details on the LEAN option.
+ *
+ * There are three possible values.
+ *
+ * Value 1:
+ * This value is associated with the 'Infinality' moniker, contributed by
+ * an individual nicknamed Infinality with the goal of making TrueType
+ * fonts render better than on Windows. A high amount of configurability
+ * and flexibility, down to rules for single glyphs in fonts, but also
+ * very slow. Its experimental and slow nature and the original
+ * developer losing interest meant that this option was never enabled in
+ * default builds.
+ *
+ * The corresponding interpreter version is v38.
+ *
+ * Value 2:
+ * The new default mode for the TrueType driver. The Infinality code
+ * base was stripped to the bare minimum and all configurability removed
+ * in the name of speed and simplicity. The configurability was mainly
+ * aimed at legacy fonts like 'Arial', 'Times New Roman', or 'Courier'.
+ * Legacy fonts are fonts that modify vertical stems to achieve clean
+ * black-and-white bitmaps. The new mode focuses on applying a minimal
+ * set of rules to all fonts indiscriminately so that modern and web
+ * fonts render well while legacy fonts render okay.
+ *
+ * The corresponding interpreter version is v40.
+ *
+ * Value 3:
+ * Compile both, making both v38 and v40 available (the latter is the
+ * default).
+ *
+ * By undefining these, you get rendering behavior like on Windows without
+ * ClearType, i.e., Windows XP without ClearType enabled and Win9x
+ * (interpreter version v35). Or not, depending on how much hinting blood
+ * and testing tears the font designer put into a given font. If you
+ * define one or both subpixel hinting options, you can switch between
+ * between v35 and the ones you define (using `FT_Property_Set`).
+ *
+ * This option requires `TT_CONFIG_OPTION_BYTECODE_INTERPRETER` to be
+ * defined.
+ *
+ * [1]
+ * https://www.microsoft.com/typography/cleartype/truetypecleartype.aspx
+ */
/* #define TT_CONFIG_OPTION_SUBPIXEL_HINTING 1 */
#define TT_CONFIG_OPTION_SUBPIXEL_HINTING 2
/* #define TT_CONFIG_OPTION_SUBPIXEL_HINTING ( 1 | 2 ) */
- /*************************************************************************/
- /* */
- /* Define TT_CONFIG_OPTION_COMPONENT_OFFSET_SCALED to compile the */
- /* TrueType glyph loader to use Apple's definition of how to handle */
- /* component offsets in composite glyphs. */
- /* */
- /* Apple and MS disagree on the default behavior of component offsets */
- /* in composites. Apple says that they should be scaled by the scaling */
- /* factors in the transformation matrix (roughly, it's more complex) */
- /* while MS says they should not. OpenType defines two bits in the */
- /* composite flags array which can be used to disambiguate, but old */
- /* fonts will not have them. */
- /* */
- /* https://www.microsoft.com/typography/otspec/glyf.htm */
- /* https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6glyf.html */
- /* */
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_COMPONENT_OFFSET_SCALED` to compile the
+ * TrueType glyph loader to use Apple's definition of how to handle
+ * component offsets in composite glyphs.
+ *
+ * Apple and MS disagree on the default behavior of component offsets in
+ * composites. Apple says that they should be scaled by the scaling
+ * factors in the transformation matrix (roughly, it's more complex) while
+ * MS says they should not. OpenType defines two bits in the composite
+ * flags array which can be used to disambiguate, but old fonts will not
+ * have them.
+ *
+ * https://www.microsoft.com/typography/otspec/glyf.htm
+ * https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6glyf.html
+ */
#undef TT_CONFIG_OPTION_COMPONENT_OFFSET_SCALED
- /*************************************************************************/
- /* */
- /* Define TT_CONFIG_OPTION_GX_VAR_SUPPORT if you want to include */
- /* support for Apple's distortable font technology (fvar, gvar, cvar, */
- /* and avar tables). This has many similarities to Type 1 Multiple */
- /* Masters support. */
- /* */
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_GX_VAR_SUPPORT` if you want to include support
+ * for Apple's distortable font technology ('fvar', 'gvar', 'cvar', and
+ * 'avar' tables). Tagged 'Font Variations', this is now part of OpenType
+ * also. This has many similarities to Type~1 Multiple Masters support.
+ */
#define TT_CONFIG_OPTION_GX_VAR_SUPPORT
- /*************************************************************************/
- /* */
- /* Define TT_CONFIG_OPTION_BDF if you want to include support for */
- /* an embedded `BDF ' table within SFNT-based bitmap formats. */
- /* */
+ /**************************************************************************
+ *
+ * Define `TT_CONFIG_OPTION_BDF` if you want to include support for an
+ * embedded 'BDF~' table within SFNT-based bitmap formats.
+ */
#define TT_CONFIG_OPTION_BDF
- /*************************************************************************/
- /* */
- /* Option TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES controls the maximum */
- /* number of bytecode instructions executed for a single run of the */
- /* bytecode interpreter, needed to prevent infinite loops. You don't */
- /* want to change this except for very special situations (e.g., making */
- /* a library fuzzer spend less time to handle broken fonts). */
- /* */
- /* It is not expected that this value is ever modified by a configuring */
- /* script; instead, it gets surrounded with #ifndef ... #endif so that */
- /* the value can be set as a preprocessor option on the compiler's */
- /* command line. */
- /* */
+ /**************************************************************************
+ *
+ * Option `TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES` controls the maximum
+ * number of bytecode instructions executed for a single run of the
+ * bytecode interpreter, needed to prevent infinite loops. You don't want
+ * to change this except for very special situations (e.g., making a
+ * library fuzzer spend less time to handle broken fonts).
+ *
+ * It is not expected that this value is ever modified by a configuring
+ * script; instead, it gets surrounded with `#ifndef ... #endif` so that
+ * the value can be set as a preprocessor option on the compiler's command
+ * line.
+ */
#ifndef TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES
#define TT_CONFIG_OPTION_MAX_RUNNABLE_OPCODES 1000000L
#endif
@@ -726,59 +726,58 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* T1_MAX_DICT_DEPTH is the maximum depth of nest dictionaries and */
- /* arrays in the Type 1 stream (see t1load.c). A minimum of 4 is */
- /* required. */
- /* */
+ /**************************************************************************
+ *
+ * `T1_MAX_DICT_DEPTH` is the maximum depth of nest dictionaries and arrays
+ * in the Type~1 stream (see `t1load.c`). A minimum of~4 is required.
+ */
#define T1_MAX_DICT_DEPTH 5
- /*************************************************************************/
- /* */
- /* T1_MAX_SUBRS_CALLS details the maximum number of nested sub-routine */
- /* calls during glyph loading. */
- /* */
+ /**************************************************************************
+ *
+ * `T1_MAX_SUBRS_CALLS` details the maximum number of nested sub-routine
+ * calls during glyph loading.
+ */
#define T1_MAX_SUBRS_CALLS 16
- /*************************************************************************/
- /* */
- /* T1_MAX_CHARSTRING_OPERANDS is the charstring stack's capacity. A */
- /* minimum of 16 is required. */
- /* */
- /* The Chinese font MingTiEG-Medium (CNS 11643 character set) needs 256. */
- /* */
+ /**************************************************************************
+ *
+ * `T1_MAX_CHARSTRING_OPERANDS` is the charstring stack's capacity. A
+ * minimum of~16 is required.
+ *
+ * The Chinese font 'MingTiEG-Medium' (covering the CNS 11643 character
+ * set) needs 256.
+ */
#define T1_MAX_CHARSTRINGS_OPERANDS 256
- /*************************************************************************/
- /* */
- /* Define this configuration macro if you want to prevent the */
- /* compilation of `t1afm', which is in charge of reading Type 1 AFM */
- /* files into an existing face. Note that if set, the T1 driver will be */
- /* unable to produce kerning distances. */
- /* */
+ /**************************************************************************
+ *
+ * Define this configuration macro if you want to prevent the compilation
+ * of the 't1afm' module, which is in charge of reading Type~1 AFM files
+ * into an existing face. Note that if set, the Type~1 driver will be
+ * unable to produce kerning distances.
+ */
#undef T1_CONFIG_OPTION_NO_AFM
- /*************************************************************************/
- /* */
- /* Define this configuration macro if you want to prevent the */
- /* compilation of the Multiple Masters font support in the Type 1 */
- /* driver. */
- /* */
+ /**************************************************************************
+ *
+ * Define this configuration macro if you want to prevent the compilation
+ * of the Multiple Masters font support in the Type~1 driver.
+ */
#undef T1_CONFIG_OPTION_NO_MM_SUPPORT
- /*************************************************************************/
- /* */
- /* T1_CONFIG_OPTION_OLD_ENGINE controls whether the pre-Adobe Type 1 */
- /* engine gets compiled into FreeType. If defined, it is possible to */
- /* switch between the two engines using the `hinting-engine' property of */
- /* the type1 driver module. */
- /* */
+ /**************************************************************************
+ *
+ * `T1_CONFIG_OPTION_OLD_ENGINE` controls whether the pre-Adobe Type~1
+ * engine gets compiled into FreeType. If defined, it is possible to
+ * switch between the two engines using the `hinting-engine` property of
+ * the 'type1' driver module.
+ */
/* #define T1_CONFIG_OPTION_OLD_ENGINE */
@@ -791,17 +790,16 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* Using CFF_CONFIG_OPTION_DARKENING_PARAMETER_{X,Y}{1,2,3,4} it is */
- /* possible to set up the default values of the four control points that */
- /* define the stem darkening behaviour of the (new) CFF engine. For */
- /* more details please read the documentation of the */
- /* `darkening-parameters' property (file `ftdriver.h'), which allows the */
- /* control at run-time. */
- /* */
- /* Do *not* undefine these macros! */
- /* */
+ /**************************************************************************
+ *
+ * Using `CFF_CONFIG_OPTION_DARKENING_PARAMETER_{X,Y}{1,2,3,4}` it is
+ * possible to set up the default values of the four control points that
+ * define the stem darkening behaviour of the (new) CFF engine. For more
+ * details please read the documentation of the `darkening-parameters`
+ * property (file `ftdriver.h`), which allows the control at run-time.
+ *
+ * Do **not** undefine these macros!
+ */
#define CFF_CONFIG_OPTION_DARKENING_PARAMETER_X1 500
#define CFF_CONFIG_OPTION_DARKENING_PARAMETER_Y1 400
@@ -815,13 +813,13 @@ FT_BEGIN_HEADER
#define CFF_CONFIG_OPTION_DARKENING_PARAMETER_Y4 0
- /*************************************************************************/
- /* */
- /* CFF_CONFIG_OPTION_OLD_ENGINE controls whether the pre-Adobe CFF */
- /* engine gets compiled into FreeType. If defined, it is possible to */
- /* switch between the two engines using the `hinting-engine' property of */
- /* the cff driver module. */
- /* */
+ /**************************************************************************
+ *
+ * `CFF_CONFIG_OPTION_OLD_ENGINE` controls whether the pre-Adobe CFF engine
+ * gets compiled into FreeType. If defined, it is possible to switch
+ * between the two engines using the `hinting-engine` property of the 'cff'
+ * driver module.
+ */
/* #define CFF_CONFIG_OPTION_OLD_ENGINE */
@@ -834,21 +832,21 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* There are many PCF fonts just called `Fixed' which look completely */
- /* different, and which have nothing to do with each other. When */
- /* selecting `Fixed' in KDE or Gnome one gets results that appear rather */
- /* random, the style changes often if one changes the size and one */
- /* cannot select some fonts at all. This option makes the PCF module */
- /* prepend the foundry name (plus a space) to the family name. */
- /* */
- /* We also check whether we have `wide' characters; all put together, we */
- /* get family names like `Sony Fixed' or `Misc Fixed Wide'. */
- /* */
- /* If this option is activated, it can be controlled with the */
- /* `no-long-family-names' property of the pcf driver module. */
- /* */
+ /**************************************************************************
+ *
+ * There are many PCF fonts just called 'Fixed' which look completely
+ * different, and which have nothing to do with each other. When selecting
+ * 'Fixed' in KDE or Gnome one gets results that appear rather random, the
+ * style changes often if one changes the size and one cannot select some
+ * fonts at all. This option makes the 'pcf' module prepend the foundry
+ * name (plus a space) to the family name.
+ *
+ * We also check whether we have 'wide' characters; all put together, we
+ * get family names like 'Sony Fixed' or 'Misc Fixed Wide'.
+ *
+ * If this option is activated, it can be controlled with the
+ * `no-long-family-names` property of the 'pcf' driver module.
+ */
/* #define PCF_CONFIG_OPTION_LONG_FAMILY_NAMES */
@@ -861,69 +859,76 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* Compile autofit module with CJK (Chinese, Japanese, Korean) script */
- /* support. */
- /* */
+ /**************************************************************************
+ *
+ * Compile 'autofit' module with CJK (Chinese, Japanese, Korean) script
+ * support.
+ */
#define AF_CONFIG_OPTION_CJK
- /*************************************************************************/
- /* */
- /* Compile autofit module with fallback Indic script support, covering */
- /* some scripts that the `latin' submodule of the autofit module doesn't */
- /* (yet) handle. */
- /* */
+
+ /**************************************************************************
+ *
+ * Compile 'autofit' module with fallback Indic script support, covering
+ * some scripts that the 'latin' submodule of the 'autofit' module doesn't
+ * (yet) handle.
+ */
#define AF_CONFIG_OPTION_INDIC
- /*************************************************************************/
- /* */
- /* Compile autofit module with warp hinting. The idea of the warping */
- /* code is to slightly scale and shift a glyph within a single dimension */
- /* so that as much of its segments are aligned (more or less) on the */
- /* grid. To find out the optimal scaling and shifting value, various */
- /* parameter combinations are tried and scored. */
- /* */
- /* This experimental option is active only if the rendering mode is */
- /* FT_RENDER_MODE_LIGHT; you can switch warping on and off with the */
- /* `warping' property of the auto-hinter (see file `ftdriver.h' for more */
- /* information; by default it is switched off). */
- /* */
+
+ /**************************************************************************
+ *
+ * Compile 'autofit' module with warp hinting. The idea of the warping
+ * code is to slightly scale and shift a glyph within a single dimension so
+ * that as much of its segments are aligned (more or less) on the grid. To
+ * find out the optimal scaling and shifting value, various parameter
+ * combinations are tried and scored.
+ *
+ * You can switch warping on and off with the `warping` property of the
+ * auto-hinter (see file `ftdriver.h` for more information; by default it
+ * is switched off).
+ *
+ * This experimental option is not active if the rendering mode is
+ * `FT_RENDER_MODE_LIGHT`.
+ */
#define AF_CONFIG_OPTION_USE_WARPER
- /*************************************************************************/
- /* */
- /* Use TrueType-like size metrics for `light' auto-hinting. */
- /* */
- /* It is strongly recommended to avoid this option, which exists only to */
- /* help some legacy applications retain its appearance and behaviour */
- /* with respect to auto-hinted TrueType fonts. */
- /* */
- /* The very reason this option exists at all are GNU/Linux distributions */
- /* like Fedora that did not un-patch the following change (which was */
- /* present in FreeType between versions 2.4.6 and 2.7.1, inclusive). */
- /* */
- /* 2011-07-16 Steven Chu <steven.f.chu@gmail.com> */
- /* */
- /* [truetype] Fix metrics on size request for scalable fonts. */
- /* */
- /* This problematic commit is now reverted (more or less). */
- /* */
+
+ /**************************************************************************
+ *
+ * Use TrueType-like size metrics for 'light' auto-hinting.
+ *
+ * It is strongly recommended to avoid this option, which exists only to
+ * help some legacy applications retain its appearance and behaviour with
+ * respect to auto-hinted TrueType fonts.
+ *
+ * The very reason this option exists at all are GNU/Linux distributions
+ * like Fedora that did not un-patch the following change (which was
+ * present in FreeType between versions 2.4.6 and 2.7.1, inclusive).
+ *
+ * ```
+ * 2011-07-16 Steven Chu <steven.f.chu@gmail.com>
+ *
+ * [truetype] Fix metrics on size request for scalable fonts.
+ * ```
+ *
+ * This problematic commit is now reverted (more or less).
+ */
/* #define AF_CONFIG_OPTION_TT_SIZE_METRICS */
/* */
/*
- * This macro is obsolete. Support has been removed in FreeType
- * version 2.5.
+ * This macro is obsolete. Support has been removed in FreeType version
+ * 2.5.
*/
/* #define FT_CONFIG_OPTION_OLD_INTERNALS */
/*
- * This macro is defined if native TrueType hinting is requested by the
- * definitions above.
+ * The next three macros are defined if native TrueType hinting is
+ * requested by the definitions above. Don't change this.
*/
#ifdef TT_CONFIG_OPTION_BYTECODE_INTERPRETER
#define TT_USE_BYTECODE_INTERPRETER
@@ -942,7 +947,7 @@ FT_BEGIN_HEADER
/*
* Check CFF darkening parameters. The checks are the same as in function
- * `cff_property_set' in file `cffdrivr.c'.
+ * `cff_property_set` in file `cffdrivr.c`.
*/
#if CFF_CONFIG_OPTION_DARKENING_PARAMETER_X1 < 0 || \
CFF_CONFIG_OPTION_DARKENING_PARAMETER_X2 < 0 || \
diff --git a/src/3rdparty/freetype/include/freetype/config/ftstdlib.h b/src/3rdparty/freetype/include/freetype/config/ftstdlib.h
index 42f9a06e43..438b6145d5 100644
--- a/src/3rdparty/freetype/include/freetype/config/ftstdlib.h
+++ b/src/3rdparty/freetype/include/freetype/config/ftstdlib.h
@@ -1,31 +1,31 @@
-/***************************************************************************/
-/* */
-/* ftstdlib.h */
-/* */
-/* ANSI-specific library and header configuration file (specification */
-/* only). */
-/* */
-/* Copyright 2002-2018 by */
-/* David Turner, Robert Wilhelm, and Werner Lemberg. */
-/* */
-/* This file is part of the FreeType project, and may only be used, */
-/* modified, and distributed under the terms of the FreeType project */
-/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
-/* this file you indicate that you have read the license and */
-/* understand and accept it fully. */
-/* */
-/***************************************************************************/
-
-
- /*************************************************************************/
- /* */
- /* This file is used to group all #includes to the ANSI C library that */
- /* FreeType normally requires. It also defines macros to rename the */
- /* standard functions within the FreeType source code. */
- /* */
- /* Load a file which defines FTSTDLIB_H_ before this one to override it. */
- /* */
- /*************************************************************************/
+/****************************************************************************
+ *
+ * ftstdlib.h
+ *
+ * ANSI-specific library and header configuration file (specification
+ * only).
+ *
+ * Copyright (C) 2002-2019 by
+ * David Turner, Robert Wilhelm, and Werner Lemberg.
+ *
+ * This file is part of the FreeType project, and may only be used,
+ * modified, and distributed under the terms of the FreeType project
+ * license, LICENSE.TXT. By continuing to use, modify, or distribute
+ * this file you indicate that you have read the license and
+ * understand and accept it fully.
+ *
+ */
+
+
+ /**************************************************************************
+ *
+ * This file is used to group all `#includes` to the ANSI~C library that
+ * FreeType normally requires. It also defines macros to rename the
+ * standard functions within the FreeType source code.
+ *
+ * Load a file which defines `FTSTDLIB_H_` before this one to override it.
+ *
+ */
#ifndef FTSTDLIB_H_
@@ -37,23 +37,23 @@
#define ft_ptrdiff_t ptrdiff_t
- /**********************************************************************/
- /* */
- /* integer limits */
- /* */
- /* UINT_MAX and ULONG_MAX are used to automatically compute the size */
- /* of `int' and `long' in bytes at compile-time. So far, this works */
- /* for all platforms the library has been tested on. */
- /* */
- /* Note that on the extremely rare platforms that do not provide */
- /* integer types that are _exactly_ 16 and 32 bits wide (e.g. some */
- /* old Crays where `int' is 36 bits), we do not make any guarantee */
- /* about the correct behaviour of FT2 with all fonts. */
- /* */
- /* In these case, `ftconfig.h' will refuse to compile anyway with a */
- /* message like `couldn't find 32-bit type' or something similar. */
- /* */
- /**********************************************************************/
+ /**************************************************************************
+ *
+ * integer limits
+ *
+ * `UINT_MAX` and `ULONG_MAX` are used to automatically compute the size of
+ * `int` and `long` in bytes at compile-time. So far, this works for all
+ * platforms the library has been tested on.
+ *
+ * Note that on the extremely rare platforms that do not provide integer
+ * types that are _exactly_ 16 and 32~bits wide (e.g., some old Crays where
+ * `int` is 36~bits), we do not make any guarantee about the correct
+ * behaviour of FreeType~2 with all fonts.
+ *
+ * In these cases, `ftconfig.h` will refuse to compile anyway with a
+ * message like 'couldn't find 32-bit type' or something similar.
+ *
+ */
#include <limits.h>
@@ -68,11 +68,11 @@
#define FT_ULONG_MAX ULONG_MAX
- /**********************************************************************/
- /* */
- /* character and string processing */
- /* */
- /**********************************************************************/
+ /**************************************************************************
+ *
+ * character and string processing
+ *
+ */
#include <string.h>
@@ -92,11 +92,11 @@
#define ft_strstr strstr
- /**********************************************************************/
- /* */
- /* file handling */
- /* */
- /**********************************************************************/
+ /**************************************************************************
+ *
+ * file handling
+ *
+ */
#include <stdio.h>
@@ -110,11 +110,11 @@
#define ft_sprintf sprintf
- /**********************************************************************/
- /* */
- /* sorting */
- /* */
- /**********************************************************************/
+ /**************************************************************************
+ *
+ * sorting
+ *
+ */
#include <stdlib.h>
@@ -122,11 +122,11 @@
#define ft_qsort qsort
- /**********************************************************************/
- /* */
- /* memory allocation */
- /* */
- /**********************************************************************/
+ /**************************************************************************
+ *
+ * memory allocation
+ *
+ */
#define ft_scalloc calloc
@@ -135,36 +135,36 @@
#define ft_srealloc realloc
- /**********************************************************************/
- /* */
- /* miscellaneous */
- /* */
- /**********************************************************************/
+ /**************************************************************************
+ *
+ * miscellaneous
+ *
+ */
#define ft_strtol strtol
#define ft_getenv getenv
- /**********************************************************************/
- /* */
- /* execution control */
- /* */
- /**********************************************************************/
+ /**************************************************************************
+ *
+ * execution control
+ *
+ */
#include <setjmp.h>
-#define ft_jmp_buf jmp_buf /* note: this cannot be a typedef since */
- /* jmp_buf is defined as a macro */
- /* on certain platforms */
+#define ft_jmp_buf jmp_buf /* note: this cannot be a typedef since */
+ /* `jmp_buf` is defined as a macro */
+ /* on certain platforms */
#define ft_longjmp longjmp
#define ft_setjmp( b ) setjmp( *(ft_jmp_buf*) &(b) ) /* same thing here */
- /* the following is only used for debugging purposes, i.e., if */
- /* FT_DEBUG_LEVEL_ERROR or FT_DEBUG_LEVEL_TRACE are defined */
+ /* The following is only used for debugging purposes, i.e., if */
+ /* `FT_DEBUG_LEVEL_ERROR` or `FT_DEBUG_LEVEL_TRACE` are defined. */
#include <stdarg.h>
diff --git a/src/3rdparty/freetype/include/freetype/freetype.h b/src/3rdparty/freetype/include/freetype/freetype.h
index 96644046e4..a6bb667e3a 100644
--- a/src/3rdparty/freetype/include/freetype/freetype.h
+++ b/src/3rdparty/freetype/include/freetype/freetype.h
@@ -1,19 +1,19 @@
-/***************************************************************************/
-/* */
-/* freetype.h */
-/* */
-/* FreeType high-level API and common types (specification only). */
-/* */
-/* Copyright 1996-2018 by */
-/* David Turner, Robert Wilhelm, and Werner Lemberg. */
-/* */
-/* This file is part of the FreeType project, and may only be used, */
-/* modified, and distributed under the terms of the FreeType project */
-/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
-/* this file you indicate that you have read the license and */
-/* understand and accept it fully. */
-/* */
-/***************************************************************************/
+/****************************************************************************
+ *
+ * freetype.h
+ *
+ * FreeType high-level API and common types (specification only).
+ *
+ * Copyright (C) 1996-2019 by
+ * David Turner, Robert Wilhelm, and Werner Lemberg.
+ *
+ * This file is part of the FreeType project, and may only be used,
+ * modified, and distributed under the terms of the FreeType project
+ * license, LICENSE.TXT. By continuing to use, modify, or distribute
+ * this file you indicate that you have read the license and
+ * understand and accept it fully.
+ *
+ */
#ifndef FREETYPE_H_
@@ -39,56 +39,55 @@ FT_BEGIN_HEADER
- /*************************************************************************/
- /* */
- /* <Section> */
- /* header_inclusion */
- /* */
- /* <Title> */
- /* FreeType's header inclusion scheme */
- /* */
- /* <Abstract> */
- /* How client applications should include FreeType header files. */
- /* */
- /* <Description> */
- /* To be as flexible as possible (and for historical reasons), */
- /* FreeType uses a very special inclusion scheme to load header */
- /* files, for example */
- /* */
- /* { */
- /* #include <ft2build.h> */
- /* */
- /* #include FT_FREETYPE_H */
- /* #include FT_OUTLINE_H */
- /* } */
- /* */
- /* A compiler and its preprocessor only needs an include path to find */
- /* the file `ft2build.h'; the exact locations and names of the other */
- /* FreeType header files are hidden by preprocessor macro names, */
- /* loaded by `ft2build.h'. The API documentation always gives the */
- /* header macro name needed for a particular function. */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * header_inclusion
+ *
+ * @title:
+ * FreeType's header inclusion scheme
+ *
+ * @abstract:
+ * How client applications should include FreeType header files.
+ *
+ * @description:
+ * To be as flexible as possible (and for historical reasons), FreeType
+ * uses a very special inclusion scheme to load header files, for example
+ *
+ * ```
+ * #include <ft2build.h>
+ *
+ * #include FT_FREETYPE_H
+ * #include FT_OUTLINE_H
+ * ```
+ *
+ * A compiler and its preprocessor only needs an include path to find the
+ * file `ft2build.h`; the exact locations and names of the other FreeType
+ * header files are hidden by @header_file_macros, loaded by
+ * `ft2build.h`. The API documentation always gives the header macro
+ * name needed for a particular function.
+ *
+ */
- /*************************************************************************/
- /* */
- /* <Section> */
- /* user_allocation */
- /* */
- /* <Title> */
- /* User allocation */
- /* */
- /* <Abstract> */
- /* How client applications should allocate FreeType data structures. */
- /* */
- /* <Description> */
- /* FreeType assumes that structures allocated by the user and passed */
- /* as arguments are zeroed out except for the actual data. In other */
- /* words, it is recommended to use `calloc' (or variants of it) */
- /* instead of `malloc' for allocation. */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * user_allocation
+ *
+ * @title:
+ * User allocation
+ *
+ * @abstract:
+ * How client applications should allocate FreeType data structures.
+ *
+ * @description:
+ * FreeType assumes that structures allocated by the user and passed as
+ * arguments are zeroed out except for the actual data. In other words,
+ * it is recommended to use `calloc` (or variants of it) instead of
+ * `malloc` for allocation.
+ *
+ */
@@ -101,219 +100,219 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* <Section> */
- /* base_interface */
- /* */
- /* <Title> */
- /* Base Interface */
- /* */
- /* <Abstract> */
- /* The FreeType~2 base font interface. */
- /* */
- /* <Description> */
- /* This section describes the most important public high-level API */
- /* functions of FreeType~2. */
- /* */
- /* <Order> */
- /* FT_Library */
- /* FT_Face */
- /* FT_Size */
- /* FT_GlyphSlot */
- /* FT_CharMap */
- /* FT_Encoding */
- /* FT_ENC_TAG */
- /* */
- /* FT_FaceRec */
- /* */
- /* FT_FACE_FLAG_SCALABLE */
- /* FT_FACE_FLAG_FIXED_SIZES */
- /* FT_FACE_FLAG_FIXED_WIDTH */
- /* FT_FACE_FLAG_HORIZONTAL */
- /* FT_FACE_FLAG_VERTICAL */
- /* FT_FACE_FLAG_COLOR */
- /* FT_FACE_FLAG_SFNT */
- /* FT_FACE_FLAG_CID_KEYED */
- /* FT_FACE_FLAG_TRICKY */
- /* FT_FACE_FLAG_KERNING */
- /* FT_FACE_FLAG_MULTIPLE_MASTERS */
- /* FT_FACE_FLAG_VARIATION */
- /* FT_FACE_FLAG_GLYPH_NAMES */
- /* FT_FACE_FLAG_EXTERNAL_STREAM */
- /* FT_FACE_FLAG_HINTER */
- /* */
- /* FT_HAS_HORIZONTAL */
- /* FT_HAS_VERTICAL */
- /* FT_HAS_KERNING */
- /* FT_HAS_FIXED_SIZES */
- /* FT_HAS_GLYPH_NAMES */
- /* FT_HAS_COLOR */
- /* FT_HAS_MULTIPLE_MASTERS */
- /* */
- /* FT_IS_SFNT */
- /* FT_IS_SCALABLE */
- /* FT_IS_FIXED_WIDTH */
- /* FT_IS_CID_KEYED */
- /* FT_IS_TRICKY */
- /* FT_IS_NAMED_INSTANCE */
- /* FT_IS_VARIATION */
- /* */
- /* FT_STYLE_FLAG_BOLD */
- /* FT_STYLE_FLAG_ITALIC */
- /* */
- /* FT_SizeRec */
- /* FT_Size_Metrics */
- /* */
- /* FT_GlyphSlotRec */
- /* FT_Glyph_Metrics */
- /* FT_SubGlyph */
- /* */
- /* FT_Bitmap_Size */
- /* */
- /* FT_Init_FreeType */
- /* FT_Done_FreeType */
- /* */
- /* FT_New_Face */
- /* FT_Done_Face */
- /* FT_Reference_Face */
- /* FT_New_Memory_Face */
- /* FT_Face_Properties */
- /* FT_Open_Face */
- /* FT_Open_Args */
- /* FT_Parameter */
- /* FT_Attach_File */
- /* FT_Attach_Stream */
- /* */
- /* FT_Set_Char_Size */
- /* FT_Set_Pixel_Sizes */
- /* FT_Request_Size */
- /* FT_Select_Size */
- /* FT_Size_Request_Type */
- /* FT_Size_RequestRec */
- /* FT_Size_Request */
- /* FT_Set_Transform */
- /* FT_Load_Glyph */
- /* FT_Get_Char_Index */
- /* FT_Get_First_Char */
- /* FT_Get_Next_Char */
- /* FT_Get_Name_Index */
- /* FT_Load_Char */
- /* */
- /* FT_OPEN_MEMORY */
- /* FT_OPEN_STREAM */
- /* FT_OPEN_PATHNAME */
- /* FT_OPEN_DRIVER */
- /* FT_OPEN_PARAMS */
- /* */
- /* FT_LOAD_DEFAULT */
- /* FT_LOAD_RENDER */
- /* FT_LOAD_MONOCHROME */
- /* FT_LOAD_LINEAR_DESIGN */
- /* FT_LOAD_NO_SCALE */
- /* FT_LOAD_NO_HINTING */
- /* FT_LOAD_NO_BITMAP */
- /* FT_LOAD_NO_AUTOHINT */
- /* FT_LOAD_COLOR */
- /* */
- /* FT_LOAD_VERTICAL_LAYOUT */
- /* FT_LOAD_IGNORE_TRANSFORM */
- /* FT_LOAD_FORCE_AUTOHINT */
- /* FT_LOAD_NO_RECURSE */
- /* FT_LOAD_PEDANTIC */
- /* */
- /* FT_LOAD_TARGET_NORMAL */
- /* FT_LOAD_TARGET_LIGHT */
- /* FT_LOAD_TARGET_MONO */
- /* FT_LOAD_TARGET_LCD */
- /* FT_LOAD_TARGET_LCD_V */
- /* */
- /* FT_LOAD_TARGET_MODE */
- /* */
- /* FT_Render_Glyph */
- /* FT_Render_Mode */
- /* FT_Get_Kerning */
- /* FT_Kerning_Mode */
- /* FT_Get_Track_Kerning */
- /* FT_Get_Glyph_Name */
- /* FT_Get_Postscript_Name */
- /* */
- /* FT_CharMapRec */
- /* FT_Select_Charmap */
- /* FT_Set_Charmap */
- /* FT_Get_Charmap_Index */
- /* */
- /* FT_Get_FSType_Flags */
- /* FT_Get_SubGlyph_Info */
- /* */
- /* FT_Face_Internal */
- /* FT_Size_Internal */
- /* FT_Slot_Internal */
- /* */
- /* FT_FACE_FLAG_XXX */
- /* FT_STYLE_FLAG_XXX */
- /* FT_OPEN_XXX */
- /* FT_LOAD_XXX */
- /* FT_LOAD_TARGET_XXX */
- /* FT_SUBGLYPH_FLAG_XXX */
- /* FT_FSTYPE_XXX */
- /* */
- /* FT_HAS_FAST_GLYPHS */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * base_interface
+ *
+ * @title:
+ * Base Interface
+ *
+ * @abstract:
+ * The FreeType~2 base font interface.
+ *
+ * @description:
+ * This section describes the most important public high-level API
+ * functions of FreeType~2.
+ *
+ * @order:
+ * FT_Library
+ * FT_Face
+ * FT_Size
+ * FT_GlyphSlot
+ * FT_CharMap
+ * FT_Encoding
+ * FT_ENC_TAG
+ *
+ * FT_FaceRec
+ *
+ * FT_FACE_FLAG_SCALABLE
+ * FT_FACE_FLAG_FIXED_SIZES
+ * FT_FACE_FLAG_FIXED_WIDTH
+ * FT_FACE_FLAG_HORIZONTAL
+ * FT_FACE_FLAG_VERTICAL
+ * FT_FACE_FLAG_COLOR
+ * FT_FACE_FLAG_SFNT
+ * FT_FACE_FLAG_CID_KEYED
+ * FT_FACE_FLAG_TRICKY
+ * FT_FACE_FLAG_KERNING
+ * FT_FACE_FLAG_MULTIPLE_MASTERS
+ * FT_FACE_FLAG_VARIATION
+ * FT_FACE_FLAG_GLYPH_NAMES
+ * FT_FACE_FLAG_EXTERNAL_STREAM
+ * FT_FACE_FLAG_HINTER
+ *
+ * FT_HAS_HORIZONTAL
+ * FT_HAS_VERTICAL
+ * FT_HAS_KERNING
+ * FT_HAS_FIXED_SIZES
+ * FT_HAS_GLYPH_NAMES
+ * FT_HAS_COLOR
+ * FT_HAS_MULTIPLE_MASTERS
+ *
+ * FT_IS_SFNT
+ * FT_IS_SCALABLE
+ * FT_IS_FIXED_WIDTH
+ * FT_IS_CID_KEYED
+ * FT_IS_TRICKY
+ * FT_IS_NAMED_INSTANCE
+ * FT_IS_VARIATION
+ *
+ * FT_STYLE_FLAG_BOLD
+ * FT_STYLE_FLAG_ITALIC
+ *
+ * FT_SizeRec
+ * FT_Size_Metrics
+ *
+ * FT_GlyphSlotRec
+ * FT_Glyph_Metrics
+ * FT_SubGlyph
+ *
+ * FT_Bitmap_Size
+ *
+ * FT_Init_FreeType
+ * FT_Done_FreeType
+ *
+ * FT_New_Face
+ * FT_Done_Face
+ * FT_Reference_Face
+ * FT_New_Memory_Face
+ * FT_Face_Properties
+ * FT_Open_Face
+ * FT_Open_Args
+ * FT_Parameter
+ * FT_Attach_File
+ * FT_Attach_Stream
+ *
+ * FT_Set_Char_Size
+ * FT_Set_Pixel_Sizes
+ * FT_Request_Size
+ * FT_Select_Size
+ * FT_Size_Request_Type
+ * FT_Size_RequestRec
+ * FT_Size_Request
+ * FT_Set_Transform
+ * FT_Load_Glyph
+ * FT_Get_Char_Index
+ * FT_Get_First_Char
+ * FT_Get_Next_Char
+ * FT_Get_Name_Index
+ * FT_Load_Char
+ *
+ * FT_OPEN_MEMORY
+ * FT_OPEN_STREAM
+ * FT_OPEN_PATHNAME
+ * FT_OPEN_DRIVER
+ * FT_OPEN_PARAMS
+ *
+ * FT_LOAD_DEFAULT
+ * FT_LOAD_RENDER
+ * FT_LOAD_MONOCHROME
+ * FT_LOAD_LINEAR_DESIGN
+ * FT_LOAD_NO_SCALE
+ * FT_LOAD_NO_HINTING
+ * FT_LOAD_NO_BITMAP
+ * FT_LOAD_NO_AUTOHINT
+ * FT_LOAD_COLOR
+ *
+ * FT_LOAD_VERTICAL_LAYOUT
+ * FT_LOAD_IGNORE_TRANSFORM
+ * FT_LOAD_FORCE_AUTOHINT
+ * FT_LOAD_NO_RECURSE
+ * FT_LOAD_PEDANTIC
+ *
+ * FT_LOAD_TARGET_NORMAL
+ * FT_LOAD_TARGET_LIGHT
+ * FT_LOAD_TARGET_MONO
+ * FT_LOAD_TARGET_LCD
+ * FT_LOAD_TARGET_LCD_V
+ *
+ * FT_LOAD_TARGET_MODE
+ *
+ * FT_Render_Glyph
+ * FT_Render_Mode
+ * FT_Get_Kerning
+ * FT_Kerning_Mode
+ * FT_Get_Track_Kerning
+ * FT_Get_Glyph_Name
+ * FT_Get_Postscript_Name
+ *
+ * FT_CharMapRec
+ * FT_Select_Charmap
+ * FT_Set_Charmap
+ * FT_Get_Charmap_Index
+ *
+ * FT_Get_FSType_Flags
+ * FT_Get_SubGlyph_Info
+ *
+ * FT_Face_Internal
+ * FT_Size_Internal
+ * FT_Slot_Internal
+ *
+ * FT_FACE_FLAG_XXX
+ * FT_STYLE_FLAG_XXX
+ * FT_OPEN_XXX
+ * FT_LOAD_XXX
+ * FT_LOAD_TARGET_XXX
+ * FT_SUBGLYPH_FLAG_XXX
+ * FT_FSTYPE_XXX
+ *
+ * FT_HAS_FAST_GLYPHS
+ *
+ */
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_Glyph_Metrics */
- /* */
- /* <Description> */
- /* A structure to model the metrics of a single glyph. The values */
- /* are expressed in 26.6 fractional pixel format; if the flag */
- /* @FT_LOAD_NO_SCALE has been used while loading the glyph, values */
- /* are expressed in font units instead. */
- /* */
- /* <Fields> */
- /* width :: */
- /* The glyph's width. */
- /* */
- /* height :: */
- /* The glyph's height. */
- /* */
- /* horiBearingX :: */
- /* Left side bearing for horizontal layout. */
- /* */
- /* horiBearingY :: */
- /* Top side bearing for horizontal layout. */
- /* */
- /* horiAdvance :: */
- /* Advance width for horizontal layout. */
- /* */
- /* vertBearingX :: */
- /* Left side bearing for vertical layout. */
- /* */
- /* vertBearingY :: */
- /* Top side bearing for vertical layout. Larger positive values */
- /* mean further below the vertical glyph origin. */
- /* */
- /* vertAdvance :: */
- /* Advance height for vertical layout. Positive values mean the */
- /* glyph has a positive advance downward. */
- /* */
- /* <Note> */
- /* If not disabled with @FT_LOAD_NO_HINTING, the values represent */
- /* dimensions of the hinted glyph (in case hinting is applicable). */
- /* */
- /* Stroking a glyph with an outside border does not increase */
- /* `horiAdvance' or `vertAdvance'; you have to manually adjust these */
- /* values to account for the added width and height. */
- /* */
- /* FreeType doesn't use the `VORG' table data for CFF fonts because */
- /* it doesn't have an interface to quickly retrieve the glyph height. */
- /* The y~coordinate of the vertical origin can be simply computed as */
- /* `vertBearingY + height' after loading a glyph. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_Glyph_Metrics
+ *
+ * @description:
+ * A structure to model the metrics of a single glyph. The values are
+ * expressed in 26.6 fractional pixel format; if the flag
+ * @FT_LOAD_NO_SCALE has been used while loading the glyph, values are
+ * expressed in font units instead.
+ *
+ * @fields:
+ * width ::
+ * The glyph's width.
+ *
+ * height ::
+ * The glyph's height.
+ *
+ * horiBearingX ::
+ * Left side bearing for horizontal layout.
+ *
+ * horiBearingY ::
+ * Top side bearing for horizontal layout.
+ *
+ * horiAdvance ::
+ * Advance width for horizontal layout.
+ *
+ * vertBearingX ::
+ * Left side bearing for vertical layout.
+ *
+ * vertBearingY ::
+ * Top side bearing for vertical layout. Larger positive values mean
+ * further below the vertical glyph origin.
+ *
+ * vertAdvance ::
+ * Advance height for vertical layout. Positive values mean the glyph
+ * has a positive advance downward.
+ *
+ * @note:
+ * If not disabled with @FT_LOAD_NO_HINTING, the values represent
+ * dimensions of the hinted glyph (in case hinting is applicable).
+ *
+ * Stroking a glyph with an outside border does not increase
+ * `horiAdvance` or `vertAdvance`; you have to manually adjust these
+ * values to account for the added width and height.
+ *
+ * FreeType doesn't use the 'VORG' table data for CFF fonts because it
+ * doesn't have an interface to quickly retrieve the glyph height. The
+ * y~coordinate of the vertical origin can be simply computed as
+ * `vertBearingY + height` after loading a glyph.
+ */
typedef struct FT_Glyph_Metrics_
{
FT_Pos width;
@@ -330,44 +329,45 @@ FT_BEGIN_HEADER
} FT_Glyph_Metrics;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_Bitmap_Size */
- /* */
- /* <Description> */
- /* This structure models the metrics of a bitmap strike (i.e., a set */
- /* of glyphs for a given point size and resolution) in a bitmap font. */
- /* It is used for the `available_sizes' field of @FT_Face. */
- /* */
- /* <Fields> */
- /* height :: The vertical distance, in pixels, between two */
- /* consecutive baselines. It is always positive. */
- /* */
- /* width :: The average width, in pixels, of all glyphs in the */
- /* strike. */
- /* */
- /* size :: The nominal size of the strike in 26.6 fractional */
- /* points. This field is not very useful. */
- /* */
- /* x_ppem :: The horizontal ppem (nominal width) in 26.6 fractional */
- /* pixels. */
- /* */
- /* y_ppem :: The vertical ppem (nominal height) in 26.6 fractional */
- /* pixels. */
- /* */
- /* <Note> */
- /* Windows FNT: */
- /* The nominal size given in a FNT font is not reliable. If the */
- /* driver finds it incorrect, it sets `size' to some calculated */
- /* values, and `x_ppem' and `y_ppem' to the pixel width and height */
- /* given in the font, respectively. */
- /* */
- /* TrueType embedded bitmaps: */
- /* `size', `width', and `height' values are not contained in the */
- /* bitmap strike itself. They are computed from the global font */
- /* parameters. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_Bitmap_Size
+ *
+ * @description:
+ * This structure models the metrics of a bitmap strike (i.e., a set of
+ * glyphs for a given point size and resolution) in a bitmap font. It is
+ * used for the `available_sizes` field of @FT_Face.
+ *
+ * @fields:
+ * height ::
+ * The vertical distance, in pixels, between two consecutive baselines.
+ * It is always positive.
+ *
+ * width ::
+ * The average width, in pixels, of all glyphs in the strike.
+ *
+ * size ::
+ * The nominal size of the strike in 26.6 fractional points. This
+ * field is not very useful.
+ *
+ * x_ppem ::
+ * The horizontal ppem (nominal width) in 26.6 fractional pixels.
+ *
+ * y_ppem ::
+ * The vertical ppem (nominal height) in 26.6 fractional pixels.
+ *
+ * @note:
+ * Windows FNT:
+ * The nominal size given in a FNT font is not reliable. If the driver
+ * finds it incorrect, it sets `size` to some calculated values, and
+ * `x_ppem` and `y_ppem` to the pixel width and height given in the
+ * font, respectively.
+ *
+ * TrueType embedded bitmaps:
+ * `size`, `width`, and `height` values are not contained in the bitmap
+ * strike itself. They are computed from the global font parameters.
+ */
typedef struct FT_Bitmap_Size_
{
FT_Short height;
@@ -389,225 +389,218 @@ FT_BEGIN_HEADER
/*************************************************************************/
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Library */
- /* */
- /* <Description> */
- /* A handle to a FreeType library instance. Each `library' is */
- /* completely independent from the others; it is the `root' of a set */
- /* of objects like fonts, faces, sizes, etc. */
- /* */
- /* It also embeds a memory manager (see @FT_Memory), as well as a */
- /* scan-line converter object (see @FT_Raster). */
- /* */
- /* In multi-threaded applications it is easiest to use one */
- /* `FT_Library' object per thread. In case this is too cumbersome, */
- /* a single `FT_Library' object across threads is possible also */
- /* (since FreeType version 2.5.6), as long as a mutex lock is used */
- /* around @FT_New_Face and @FT_Done_Face. */
- /* */
- /* <Note> */
- /* Library objects are normally created by @FT_Init_FreeType, and */
- /* destroyed with @FT_Done_FreeType. If you need reference-counting */
- /* (cf. @FT_Reference_Library), use @FT_New_Library and */
- /* @FT_Done_Library. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Library
+ *
+ * @description:
+ * A handle to a FreeType library instance. Each 'library' is completely
+ * independent from the others; it is the 'root' of a set of objects like
+ * fonts, faces, sizes, etc.
+ *
+ * It also embeds a memory manager (see @FT_Memory), as well as a
+ * scan-line converter object (see @FT_Raster).
+ *
+ * [Since 2.5.6] In multi-threaded applications it is easiest to use one
+ * `FT_Library` object per thread. In case this is too cumbersome, a
+ * single `FT_Library` object across threads is possible also, as long as
+ * a mutex lock is used around @FT_New_Face and @FT_Done_Face.
+ *
+ * @note:
+ * Library objects are normally created by @FT_Init_FreeType, and
+ * destroyed with @FT_Done_FreeType. If you need reference-counting
+ * (cf. @FT_Reference_Library), use @FT_New_Library and @FT_Done_Library.
+ */
typedef struct FT_LibraryRec_ *FT_Library;
- /*************************************************************************/
- /* */
- /* <Section> */
- /* module_management */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * module_management
+ *
+ */
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Module */
- /* */
- /* <Description> */
- /* A handle to a given FreeType module object. A module can be a */
- /* font driver, a renderer, or anything else that provides services */
- /* to the former. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Module
+ *
+ * @description:
+ * A handle to a given FreeType module object. A module can be a font
+ * driver, a renderer, or anything else that provides services to the
+ * former.
+ */
typedef struct FT_ModuleRec_* FT_Module;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Driver */
- /* */
- /* <Description> */
- /* A handle to a given FreeType font driver object. A font driver */
- /* is a module capable of creating faces from font files. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Driver
+ *
+ * @description:
+ * A handle to a given FreeType font driver object. A font driver is a
+ * module capable of creating faces from font files.
+ */
typedef struct FT_DriverRec_* FT_Driver;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Renderer */
- /* */
- /* <Description> */
- /* A handle to a given FreeType renderer. A renderer is a module in */
- /* charge of converting a glyph's outline image to a bitmap. It */
- /* supports a single glyph image format, and one or more target */
- /* surface depths. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Renderer
+ *
+ * @description:
+ * A handle to a given FreeType renderer. A renderer is a module in
+ * charge of converting a glyph's outline image to a bitmap. It supports
+ * a single glyph image format, and one or more target surface depths.
+ */
typedef struct FT_RendererRec_* FT_Renderer;
- /*************************************************************************/
- /* */
- /* <Section> */
- /* base_interface */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * base_interface
+ *
+ */
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Face */
- /* */
- /* <Description> */
- /* A handle to a typographic face object. A face object models a */
- /* given typeface, in a given style. */
- /* */
- /* <Note> */
- /* A face object also owns a single @FT_GlyphSlot object, as well */
- /* as one or more @FT_Size objects. */
- /* */
- /* Use @FT_New_Face or @FT_Open_Face to create a new face object from */
- /* a given filepath or a custom input stream. */
- /* */
- /* Use @FT_Done_Face to destroy it (along with its slot and sizes). */
- /* */
- /* An `FT_Face' object can only be safely used from one thread at a */
- /* time. Similarly, creation and destruction of `FT_Face' with the */
- /* same @FT_Library object can only be done from one thread at a */
- /* time. On the other hand, functions like @FT_Load_Glyph and its */
- /* siblings are thread-safe and do not need the lock to be held as */
- /* long as the same `FT_Face' object is not used from multiple */
- /* threads at the same time. */
- /* */
- /* <Also> */
- /* See @FT_FaceRec for the publicly accessible fields of a given face */
- /* object. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Face
+ *
+ * @description:
+ * A handle to a typographic face object. A face object models a given
+ * typeface, in a given style.
+ *
+ * @note:
+ * A face object also owns a single @FT_GlyphSlot object, as well as one
+ * or more @FT_Size objects.
+ *
+ * Use @FT_New_Face or @FT_Open_Face to create a new face object from a
+ * given filepath or a custom input stream.
+ *
+ * Use @FT_Done_Face to destroy it (along with its slot and sizes).
+ *
+ * An `FT_Face` object can only be safely used from one thread at a time.
+ * Similarly, creation and destruction of `FT_Face` with the same
+ * @FT_Library object can only be done from one thread at a time. On the
+ * other hand, functions like @FT_Load_Glyph and its siblings are
+ * thread-safe and do not need the lock to be held as long as the same
+ * `FT_Face` object is not used from multiple threads at the same time.
+ *
+ * @also:
+ * See @FT_FaceRec for the publicly accessible fields of a given face
+ * object.
+ */
typedef struct FT_FaceRec_* FT_Face;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Size */
- /* */
- /* <Description> */
- /* A handle to an object that models a face scaled to a given */
- /* character size. */
- /* */
- /* <Note> */
- /* An @FT_Face has one _active_ @FT_Size object that is used by */
- /* functions like @FT_Load_Glyph to determine the scaling */
- /* transformation that in turn is used to load and hint glyphs and */
- /* metrics. */
- /* */
- /* You can use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, */
- /* @FT_Request_Size or even @FT_Select_Size to change the content */
- /* (i.e., the scaling values) of the active @FT_Size. */
- /* */
- /* You can use @FT_New_Size to create additional size objects for a */
- /* given @FT_Face, but they won't be used by other functions until */
- /* you activate it through @FT_Activate_Size. Only one size can be */
- /* activated at any given time per face. */
- /* */
- /* <Also> */
- /* See @FT_SizeRec for the publicly accessible fields of a given size */
- /* object. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Size
+ *
+ * @description:
+ * A handle to an object that models a face scaled to a given character
+ * size.
+ *
+ * @note:
+ * An @FT_Face has one _active_ @FT_Size object that is used by functions
+ * like @FT_Load_Glyph to determine the scaling transformation that in
+ * turn is used to load and hint glyphs and metrics.
+ *
+ * You can use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, @FT_Request_Size
+ * or even @FT_Select_Size to change the content (i.e., the scaling
+ * values) of the active @FT_Size.
+ *
+ * You can use @FT_New_Size to create additional size objects for a given
+ * @FT_Face, but they won't be used by other functions until you activate
+ * it through @FT_Activate_Size. Only one size can be activated at any
+ * given time per face.
+ *
+ * @also:
+ * See @FT_SizeRec for the publicly accessible fields of a given size
+ * object.
+ */
typedef struct FT_SizeRec_* FT_Size;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_GlyphSlot */
- /* */
- /* <Description> */
- /* A handle to a given `glyph slot'. A slot is a container that can */
- /* hold any of the glyphs contained in its parent face. */
- /* */
- /* In other words, each time you call @FT_Load_Glyph or */
- /* @FT_Load_Char, the slot's content is erased by the new glyph data, */
- /* i.e., the glyph's metrics, its image (bitmap or outline), and */
- /* other control information. */
- /* */
- /* <Also> */
- /* See @FT_GlyphSlotRec for the publicly accessible glyph fields. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_GlyphSlot
+ *
+ * @description:
+ * A handle to a given 'glyph slot'. A slot is a container that can hold
+ * any of the glyphs contained in its parent face.
+ *
+ * In other words, each time you call @FT_Load_Glyph or @FT_Load_Char,
+ * the slot's content is erased by the new glyph data, i.e., the glyph's
+ * metrics, its image (bitmap or outline), and other control information.
+ *
+ * @also:
+ * See @FT_GlyphSlotRec for the publicly accessible glyph fields.
+ */
typedef struct FT_GlyphSlotRec_* FT_GlyphSlot;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_CharMap */
- /* */
- /* <Description> */
- /* A handle to a character map (usually abbreviated to `charmap'). A */
- /* charmap is used to translate character codes in a given encoding */
- /* into glyph indexes for its parent's face. Some font formats may */
- /* provide several charmaps per font. */
- /* */
- /* Each face object owns zero or more charmaps, but only one of them */
- /* can be `active', providing the data used by @FT_Get_Char_Index or */
- /* @FT_Load_Char. */
- /* */
- /* The list of available charmaps in a face is available through the */
- /* `face->num_charmaps' and `face->charmaps' fields of @FT_FaceRec. */
- /* */
- /* The currently active charmap is available as `face->charmap'. */
- /* You should call @FT_Set_Charmap to change it. */
- /* */
- /* <Note> */
- /* When a new face is created (either through @FT_New_Face or */
- /* @FT_Open_Face), the library looks for a Unicode charmap within */
- /* the list and automatically activates it. If there is no Unicode */
- /* charmap, FreeType doesn't set an `active' charmap. */
- /* */
- /* <Also> */
- /* See @FT_CharMapRec for the publicly accessible fields of a given */
- /* character map. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_CharMap
+ *
+ * @description:
+ * A handle to a character map (usually abbreviated to 'charmap'). A
+ * charmap is used to translate character codes in a given encoding into
+ * glyph indexes for its parent's face. Some font formats may provide
+ * several charmaps per font.
+ *
+ * Each face object owns zero or more charmaps, but only one of them can
+ * be 'active', providing the data used by @FT_Get_Char_Index or
+ * @FT_Load_Char.
+ *
+ * The list of available charmaps in a face is available through the
+ * `face->num_charmaps` and `face->charmaps` fields of @FT_FaceRec.
+ *
+ * The currently active charmap is available as `face->charmap`. You
+ * should call @FT_Set_Charmap to change it.
+ *
+ * @note:
+ * When a new face is created (either through @FT_New_Face or
+ * @FT_Open_Face), the library looks for a Unicode charmap within the
+ * list and automatically activates it. If there is no Unicode charmap,
+ * FreeType doesn't set an 'active' charmap.
+ *
+ * @also:
+ * See @FT_CharMapRec for the publicly accessible fields of a given
+ * character map.
+ */
typedef struct FT_CharMapRec_* FT_CharMap;
- /*************************************************************************/
- /* */
- /* <Macro> */
- /* FT_ENC_TAG */
- /* */
- /* <Description> */
- /* This macro converts four-letter tags into an unsigned long. It is */
- /* used to define `encoding' identifiers (see @FT_Encoding). */
- /* */
- /* <Note> */
- /* Since many 16-bit compilers don't like 32-bit enumerations, you */
- /* should redefine this macro in case of problems to something like */
- /* this: */
- /* */
- /* { */
- /* #define FT_ENC_TAG( value, a, b, c, d ) value */
- /* } */
- /* */
- /* to get a simple enumeration without assigning special numbers. */
- /* */
+ /**************************************************************************
+ *
+ * @macro:
+ * FT_ENC_TAG
+ *
+ * @description:
+ * This macro converts four-letter tags into an unsigned long. It is
+ * used to define 'encoding' identifiers (see @FT_Encoding).
+ *
+ * @note:
+ * Since many 16-bit compilers don't like 32-bit enumerations, you should
+ * redefine this macro in case of problems to something like this:
+ *
+ * ```
+ * #define FT_ENC_TAG( value, a, b, c, d ) value
+ * ```
+ *
+ * to get a simple enumeration without assigning special numbers.
+ */
#ifndef FT_ENC_TAG
#define FT_ENC_TAG( value, a, b, c, d ) \
@@ -619,150 +612,147 @@ FT_BEGIN_HEADER
#endif /* FT_ENC_TAG */
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* FT_Encoding */
- /* */
- /* <Description> */
- /* An enumeration to specify character sets supported by charmaps. */
- /* Used in the @FT_Select_Charmap API function. */
- /* */
- /* <Note> */
- /* Despite the name, this enumeration lists specific character */
- /* repertories (i.e., charsets), and not text encoding methods (e.g., */
- /* UTF-8, UTF-16, etc.). */
- /* */
- /* Other encodings might be defined in the future. */
- /* */
- /* <Values> */
- /* FT_ENCODING_NONE :: */
- /* The encoding value~0 is reserved. */
- /* */
- /* FT_ENCODING_UNICODE :: */
- /* The Unicode character set. This value covers all versions of */
- /* the Unicode repertoire, including ASCII and Latin-1. Most fonts */
- /* include a Unicode charmap, but not all of them. */
- /* */
- /* For example, if you want to access Unicode value U+1F028 (and */
- /* the font contains it), use value 0x1F028 as the input value for */
- /* @FT_Get_Char_Index. */
- /* */
- /* FT_ENCODING_MS_SYMBOL :: */
- /* Microsoft Symbol encoding, used to encode mathematical symbols */
- /* and wingdings. For more information, see */
- /* `https://www.microsoft.com/typography/otspec/recom.htm', */
- /* `http://www.kostis.net/charsets/symbol.htm', and */
- /* `http://www.kostis.net/charsets/wingding.htm'. */
- /* */
- /* This encoding uses character codes from the PUA (Private Unicode */
- /* Area) in the range U+F020-U+F0FF. */
- /* */
- /* FT_ENCODING_SJIS :: */
- /* Shift JIS encoding for Japanese. More info at */
- /* `https://en.wikipedia.org/wiki/Shift_JIS'. See note on */
- /* multi-byte encodings below. */
- /* */
- /* FT_ENCODING_PRC :: */
- /* Corresponds to encoding systems mainly for Simplified Chinese as */
- /* used in People's Republic of China (PRC). The encoding layout */
- /* is based on GB~2312 and its supersets GBK and GB~18030. */
- /* */
- /* FT_ENCODING_BIG5 :: */
- /* Corresponds to an encoding system for Traditional Chinese as */
- /* used in Taiwan and Hong Kong. */
- /* */
- /* FT_ENCODING_WANSUNG :: */
- /* Corresponds to the Korean encoding system known as Extended */
- /* Wansung (MS Windows code page 949). */
- /* For more information see */
- /* `https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit949.txt'. */
- /* */
- /* FT_ENCODING_JOHAB :: */
- /* The Korean standard character set (KS~C 5601-1992), which */
- /* corresponds to MS Windows code page 1361. This character set */
- /* includes all possible Hangul character combinations. */
- /* */
- /* FT_ENCODING_ADOBE_LATIN_1 :: */
- /* Corresponds to a Latin-1 encoding as defined in a Type~1 */
- /* PostScript font. It is limited to 256 character codes. */
- /* */
- /* FT_ENCODING_ADOBE_STANDARD :: */
- /* Adobe Standard encoding, as found in Type~1, CFF, and */
- /* OpenType/CFF fonts. It is limited to 256 character codes. */
- /* */
- /* FT_ENCODING_ADOBE_EXPERT :: */
- /* Adobe Expert encoding, as found in Type~1, CFF, and OpenType/CFF */
- /* fonts. It is limited to 256 character codes. */
- /* */
- /* FT_ENCODING_ADOBE_CUSTOM :: */
- /* Corresponds to a custom encoding, as found in Type~1, CFF, and */
- /* OpenType/CFF fonts. It is limited to 256 character codes. */
- /* */
- /* FT_ENCODING_APPLE_ROMAN :: */
- /* Apple roman encoding. Many TrueType and OpenType fonts contain */
- /* a charmap for this 8-bit encoding, since older versions of Mac */
- /* OS are able to use it. */
- /* */
- /* FT_ENCODING_OLD_LATIN_2 :: */
- /* This value is deprecated and was neither used nor reported by */
- /* FreeType. Don't use or test for it. */
- /* */
- /* FT_ENCODING_MS_SJIS :: */
- /* Same as FT_ENCODING_SJIS. Deprecated. */
- /* */
- /* FT_ENCODING_MS_GB2312 :: */
- /* Same as FT_ENCODING_PRC. Deprecated. */
- /* */
- /* FT_ENCODING_MS_BIG5 :: */
- /* Same as FT_ENCODING_BIG5. Deprecated. */
- /* */
- /* FT_ENCODING_MS_WANSUNG :: */
- /* Same as FT_ENCODING_WANSUNG. Deprecated. */
- /* */
- /* FT_ENCODING_MS_JOHAB :: */
- /* Same as FT_ENCODING_JOHAB. Deprecated. */
- /* */
- /* <Note> */
- /* By default, FreeType enables a Unicode charmap and tags it with */
- /* FT_ENCODING_UNICODE when it is either provided or can be generated */
- /* from PostScript glyph name dictionaries in the font file. */
- /* All other encodings are considered legacy and tagged only if */
- /* explicitly defined in the font file. Otherwise, FT_ENCODING_NONE */
- /* is used. */
- /* */
- /* FT_ENCODING_NONE is set by the BDF and PCF drivers if the charmap */
- /* is neither Unicode nor ISO-8859-1 (otherwise it is set to */
- /* FT_ENCODING_UNICODE). Use @FT_Get_BDF_Charset_ID to find out */
- /* which encoding is really present. If, for example, the */
- /* `cs_registry' field is `KOI8' and the `cs_encoding' field is `R', */
- /* the font is encoded in KOI8-R. */
- /* */
- /* FT_ENCODING_NONE is always set (with a single exception) by the */
- /* winfonts driver. Use @FT_Get_WinFNT_Header and examine the */
- /* `charset' field of the @FT_WinFNT_HeaderRec structure to find out */
- /* which encoding is really present. For example, */
- /* @FT_WinFNT_ID_CP1251 (204) means Windows code page 1251 (for */
- /* Russian). */
- /* */
- /* FT_ENCODING_NONE is set if `platform_id' is @TT_PLATFORM_MACINTOSH */
- /* and `encoding_id' is not `TT_MAC_ID_ROMAN' (otherwise it is set to */
- /* FT_ENCODING_APPLE_ROMAN). */
- /* */
- /* If `platform_id' is @TT_PLATFORM_MACINTOSH, use the function */
- /* @FT_Get_CMap_Language_ID to query the Mac language ID that may */
- /* be needed to be able to distinguish Apple encoding variants. See */
- /* */
- /* https://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt */
- /* */
- /* to get an idea how to do that. Basically, if the language ID */
- /* is~0, don't use it, otherwise subtract 1 from the language ID. */
- /* Then examine `encoding_id'. If, for example, `encoding_id' is */
- /* `TT_MAC_ID_ROMAN' and the language ID (minus~1) is */
- /* `TT_MAC_LANGID_GREEK', it is the Greek encoding, not Roman. */
- /* `TT_MAC_ID_ARABIC' with `TT_MAC_LANGID_FARSI' means the Farsi */
- /* variant the Arabic encoding. */
- /* */
+ /**************************************************************************
+ *
+ * @enum:
+ * FT_Encoding
+ *
+ * @description:
+ * An enumeration to specify character sets supported by charmaps. Used
+ * in the @FT_Select_Charmap API function.
+ *
+ * @note:
+ * Despite the name, this enumeration lists specific character
+ * repertories (i.e., charsets), and not text encoding methods (e.g.,
+ * UTF-8, UTF-16, etc.).
+ *
+ * Other encodings might be defined in the future.
+ *
+ * @values:
+ * FT_ENCODING_NONE ::
+ * The encoding value~0 is reserved for all formats except BDF, PCF,
+ * and Windows FNT; see below for more information.
+ *
+ * FT_ENCODING_UNICODE ::
+ * The Unicode character set. This value covers all versions of the
+ * Unicode repertoire, including ASCII and Latin-1. Most fonts include
+ * a Unicode charmap, but not all of them.
+ *
+ * For example, if you want to access Unicode value U+1F028 (and the
+ * font contains it), use value 0x1F028 as the input value for
+ * @FT_Get_Char_Index.
+ *
+ * FT_ENCODING_MS_SYMBOL ::
+ * Microsoft Symbol encoding, used to encode mathematical symbols and
+ * wingdings. For more information, see
+ * 'https://www.microsoft.com/typography/otspec/recom.htm#non-standard-symbol-fonts',
+ * 'http://www.kostis.net/charsets/symbol.htm', and
+ * 'http://www.kostis.net/charsets/wingding.htm'.
+ *
+ * This encoding uses character codes from the PUA (Private Unicode
+ * Area) in the range U+F020-U+F0FF.
+ *
+ * FT_ENCODING_SJIS ::
+ * Shift JIS encoding for Japanese. More info at
+ * 'https://en.wikipedia.org/wiki/Shift_JIS'. See note on multi-byte
+ * encodings below.
+ *
+ * FT_ENCODING_PRC ::
+ * Corresponds to encoding systems mainly for Simplified Chinese as
+ * used in People's Republic of China (PRC). The encoding layout is
+ * based on GB~2312 and its supersets GBK and GB~18030.
+ *
+ * FT_ENCODING_BIG5 ::
+ * Corresponds to an encoding system for Traditional Chinese as used in
+ * Taiwan and Hong Kong.
+ *
+ * FT_ENCODING_WANSUNG ::
+ * Corresponds to the Korean encoding system known as Extended Wansung
+ * (MS Windows code page 949). For more information see
+ * 'https://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WindowsBestFit/bestfit949.txt'.
+ *
+ * FT_ENCODING_JOHAB ::
+ * The Korean standard character set (KS~C 5601-1992), which
+ * corresponds to MS Windows code page 1361. This character set
+ * includes all possible Hangul character combinations.
+ *
+ * FT_ENCODING_ADOBE_LATIN_1 ::
+ * Corresponds to a Latin-1 encoding as defined in a Type~1 PostScript
+ * font. It is limited to 256 character codes.
+ *
+ * FT_ENCODING_ADOBE_STANDARD ::
+ * Adobe Standard encoding, as found in Type~1, CFF, and OpenType/CFF
+ * fonts. It is limited to 256 character codes.
+ *
+ * FT_ENCODING_ADOBE_EXPERT ::
+ * Adobe Expert encoding, as found in Type~1, CFF, and OpenType/CFF
+ * fonts. It is limited to 256 character codes.
+ *
+ * FT_ENCODING_ADOBE_CUSTOM ::
+ * Corresponds to a custom encoding, as found in Type~1, CFF, and
+ * OpenType/CFF fonts. It is limited to 256 character codes.
+ *
+ * FT_ENCODING_APPLE_ROMAN ::
+ * Apple roman encoding. Many TrueType and OpenType fonts contain a
+ * charmap for this 8-bit encoding, since older versions of Mac OS are
+ * able to use it.
+ *
+ * FT_ENCODING_OLD_LATIN_2 ::
+ * This value is deprecated and was neither used nor reported by
+ * FreeType. Don't use or test for it.
+ *
+ * FT_ENCODING_MS_SJIS ::
+ * Same as FT_ENCODING_SJIS. Deprecated.
+ *
+ * FT_ENCODING_MS_GB2312 ::
+ * Same as FT_ENCODING_PRC. Deprecated.
+ *
+ * FT_ENCODING_MS_BIG5 ::
+ * Same as FT_ENCODING_BIG5. Deprecated.
+ *
+ * FT_ENCODING_MS_WANSUNG ::
+ * Same as FT_ENCODING_WANSUNG. Deprecated.
+ *
+ * FT_ENCODING_MS_JOHAB ::
+ * Same as FT_ENCODING_JOHAB. Deprecated.
+ *
+ * @note:
+ * By default, FreeType enables a Unicode charmap and tags it with
+ * `FT_ENCODING_UNICODE` when it is either provided or can be generated
+ * from PostScript glyph name dictionaries in the font file. All other
+ * encodings are considered legacy and tagged only if explicitly defined
+ * in the font file. Otherwise, `FT_ENCODING_NONE` is used.
+ *
+ * `FT_ENCODING_NONE` is set by the BDF and PCF drivers if the charmap is
+ * neither Unicode nor ISO-8859-1 (otherwise it is set to
+ * `FT_ENCODING_UNICODE`). Use @FT_Get_BDF_Charset_ID to find out which
+ * encoding is really present. If, for example, the `cs_registry` field
+ * is 'KOI8' and the `cs_encoding` field is 'R', the font is encoded in
+ * KOI8-R.
+ *
+ * `FT_ENCODING_NONE` is always set (with a single exception) by the
+ * winfonts driver. Use @FT_Get_WinFNT_Header and examine the `charset`
+ * field of the @FT_WinFNT_HeaderRec structure to find out which encoding
+ * is really present. For example, @FT_WinFNT_ID_CP1251 (204) means
+ * Windows code page 1251 (for Russian).
+ *
+ * `FT_ENCODING_NONE` is set if `platform_id` is @TT_PLATFORM_MACINTOSH
+ * and `encoding_id` is not `TT_MAC_ID_ROMAN` (otherwise it is set to
+ * `FT_ENCODING_APPLE_ROMAN`).
+ *
+ * If `platform_id` is @TT_PLATFORM_MACINTOSH, use the function
+ * @FT_Get_CMap_Language_ID to query the Mac language ID that may be
+ * needed to be able to distinguish Apple encoding variants. See
+ *
+ * https://www.unicode.org/Public/MAPPINGS/VENDORS/APPLE/Readme.txt
+ *
+ * to get an idea how to do that. Basically, if the language ID is~0,
+ * don't use it, otherwise subtract 1 from the language ID. Then examine
+ * `encoding_id`. If, for example, `encoding_id` is `TT_MAC_ID_ROMAN`
+ * and the language ID (minus~1) is `TT_MAC_LANGID_GREEK`, it is the
+ * Greek encoding, not Roman. `TT_MAC_ID_ARABIC` with
+ * `TT_MAC_LANGID_FARSI` means the Farsi variant the Arabic encoding.
+ */
typedef enum FT_Encoding_
{
FT_ENC_TAG( FT_ENCODING_NONE, 0, 0, 0, 0 ),
@@ -796,7 +786,7 @@ FT_BEGIN_HEADER
} FT_Encoding;
- /* these constants are deprecated; use the corresponding `FT_Encoding' */
+ /* these constants are deprecated; use the corresponding `FT_Encoding` */
/* values instead */
#define ft_encoding_none FT_ENCODING_NONE
#define ft_encoding_unicode FT_ENCODING_UNICODE
@@ -815,29 +805,31 @@ FT_BEGIN_HEADER
#define ft_encoding_apple_roman FT_ENCODING_APPLE_ROMAN
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_CharMapRec */
- /* */
- /* <Description> */
- /* The base charmap structure. */
- /* */
- /* <Fields> */
- /* face :: A handle to the parent face object. */
- /* */
- /* encoding :: An @FT_Encoding tag identifying the charmap. Use */
- /* this with @FT_Select_Charmap. */
- /* */
- /* platform_id :: An ID number describing the platform for the */
- /* following encoding ID. This comes directly from */
- /* the TrueType specification and gets emulated for */
- /* other formats. */
- /* */
- /* encoding_id :: A platform specific encoding number. This also */
- /* comes from the TrueType specification and gets */
- /* emulated similarly. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_CharMapRec
+ *
+ * @description:
+ * The base charmap structure.
+ *
+ * @fields:
+ * face ::
+ * A handle to the parent face object.
+ *
+ * encoding ::
+ * An @FT_Encoding tag identifying the charmap. Use this with
+ * @FT_Select_Charmap.
+ *
+ * platform_id ::
+ * An ID number describing the platform for the following encoding ID.
+ * This comes directly from the TrueType specification and gets
+ * emulated for other formats.
+ *
+ * encoding_id ::
+ * A platform-specific encoding number. This also comes from the
+ * TrueType specification and gets emulated similarly.
+ */
typedef struct FT_CharMapRec_
{
FT_Face face;
@@ -857,215 +849,195 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Face_Internal */
- /* */
- /* <Description> */
- /* An opaque handle to an `FT_Face_InternalRec' structure that models */
- /* the private data of a given @FT_Face object. */
- /* */
- /* This structure might change between releases of FreeType~2 and is */
- /* not generally available to client applications. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Face_Internal
+ *
+ * @description:
+ * An opaque handle to an `FT_Face_InternalRec` structure that models the
+ * private data of a given @FT_Face object.
+ *
+ * This structure might change between releases of FreeType~2 and is not
+ * generally available to client applications.
+ */
typedef struct FT_Face_InternalRec_* FT_Face_Internal;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_FaceRec */
- /* */
- /* <Description> */
- /* FreeType root face class structure. A face object models a */
- /* typeface in a font file. */
- /* */
- /* <Fields> */
- /* num_faces :: The number of faces in the font file. Some */
- /* font formats can have multiple faces in */
- /* a single font file. */
- /* */
- /* face_index :: This field holds two different values. */
- /* Bits 0-15 are the index of the face in the */
- /* font file (starting with value~0). They */
- /* are set to~0 if there is only one face in */
- /* the font file. */
- /* */
- /* [Since 2.6.1] Bits 16-30 are relevant to GX */
- /* and OpenType variation fonts only, holding */
- /* the named instance index for the current */
- /* face index (starting with value~1; value~0 */
- /* indicates font access without a named */
- /* instance). For non-variation fonts, bits */
- /* 16-30 are ignored. If we have the third */
- /* named instance of face~4, say, `face_index' */
- /* is set to 0x00030004. */
- /* */
- /* Bit 31 is always zero (this is, */
- /* `face_index' is always a positive value). */
- /* */
- /* [Since 2.9] Changing the design coordinates */
- /* with @FT_Set_Var_Design_Coordinates or */
- /* @FT_Set_Var_Blend_Coordinates does not */
- /* influence the named instance index value */
- /* (only @FT_Set_Named_Instance does that). */
- /* */
- /* face_flags :: A set of bit flags that give important */
- /* information about the face; see */
- /* @FT_FACE_FLAG_XXX for the details. */
- /* */
- /* style_flags :: The lower 16~bits contain a set of bit */
- /* flags indicating the style of the face; see */
- /* @FT_STYLE_FLAG_XXX for the details. */
- /* */
- /* [Since 2.6.1] Bits 16-30 hold the number */
- /* of named instances available for the */
- /* current face if we have a GX or OpenType */
- /* variation (sub)font. Bit 31 is always zero */
- /* (this is, `style_flags' is always a */
- /* positive value). Note that a variation */
- /* font has always at least one named */
- /* instance, namely the default instance. */
- /* */
- /* num_glyphs :: The number of glyphs in the face. If the */
- /* face is scalable and has sbits (see */
- /* `num_fixed_sizes'), it is set to the number */
- /* of outline glyphs. */
- /* */
- /* For CID-keyed fonts (not in an SFNT */
- /* wrapper) this value gives the highest CID */
- /* used in the font. */
- /* */
- /* family_name :: The face's family name. This is an ASCII */
- /* string, usually in English, that describes */
- /* the typeface's family (like `Times New */
- /* Roman', `Bodoni', `Garamond', etc). This */
- /* is a least common denominator used to list */
- /* fonts. Some formats (TrueType & OpenType) */
- /* provide localized and Unicode versions of */
- /* this string. Applications should use the */
- /* format specific interface to access them. */
- /* Can be NULL (e.g., in fonts embedded in a */
- /* PDF file). */
- /* */
- /* In case the font doesn't provide a specific */
- /* family name entry, FreeType tries to */
- /* synthesize one, deriving it from other name */
- /* entries. */
- /* */
- /* style_name :: The face's style name. This is an ASCII */
- /* string, usually in English, that describes */
- /* the typeface's style (like `Italic', */
- /* `Bold', `Condensed', etc). Not all font */
- /* formats provide a style name, so this field */
- /* is optional, and can be set to NULL. As */
- /* for `family_name', some formats provide */
- /* localized and Unicode versions of this */
- /* string. Applications should use the format */
- /* specific interface to access them. */
- /* */
- /* num_fixed_sizes :: The number of bitmap strikes in the face. */
- /* Even if the face is scalable, there might */
- /* still be bitmap strikes, which are called */
- /* `sbits' in that case. */
- /* */
- /* available_sizes :: An array of @FT_Bitmap_Size for all bitmap */
- /* strikes in the face. It is set to NULL if */
- /* there is no bitmap strike. */
- /* */
- /* Note that FreeType tries to sanitize the */
- /* strike data since they are sometimes sloppy */
- /* or incorrect, but this can easily fail. */
- /* */
- /* num_charmaps :: The number of charmaps in the face. */
- /* */
- /* charmaps :: An array of the charmaps of the face. */
- /* */
- /* generic :: A field reserved for client uses. See the */
- /* @FT_Generic type description. */
- /* */
- /* bbox :: The font bounding box. Coordinates are */
- /* expressed in font units (see */
- /* `units_per_EM'). The box is large enough */
- /* to contain any glyph from the font. Thus, */
- /* `bbox.yMax' can be seen as the `maximum */
- /* ascender', and `bbox.yMin' as the `minimum */
- /* descender'. Only relevant for scalable */
- /* formats. */
- /* */
- /* Note that the bounding box might be off by */
- /* (at least) one pixel for hinted fonts. See */
- /* @FT_Size_Metrics for further discussion. */
- /* */
- /* units_per_EM :: The number of font units per EM square for */
- /* this face. This is typically 2048 for */
- /* TrueType fonts, and 1000 for Type~1 fonts. */
- /* Only relevant for scalable formats. */
- /* */
- /* ascender :: The typographic ascender of the face, */
- /* expressed in font units. For font formats */
- /* not having this information, it is set to */
- /* `bbox.yMax'. Only relevant for scalable */
- /* formats. */
- /* */
- /* descender :: The typographic descender of the face, */
- /* expressed in font units. For font formats */
- /* not having this information, it is set to */
- /* `bbox.yMin'. Note that this field is */
- /* negative for values below the baseline. */
- /* Only relevant for scalable formats. */
- /* */
- /* height :: This value is the vertical distance */
- /* between two consecutive baselines, */
- /* expressed in font units. It is always */
- /* positive. Only relevant for scalable */
- /* formats. */
- /* */
- /* If you want the global glyph height, use */
- /* `ascender - descender'. */
- /* */
- /* max_advance_width :: The maximum advance width, in font units, */
- /* for all glyphs in this face. This can be */
- /* used to make word wrapping computations */
- /* faster. Only relevant for scalable */
- /* formats. */
- /* */
- /* max_advance_height :: The maximum advance height, in font units, */
- /* for all glyphs in this face. This is only */
- /* relevant for vertical layouts, and is set */
- /* to `height' for fonts that do not provide */
- /* vertical metrics. Only relevant for */
- /* scalable formats. */
- /* */
- /* underline_position :: The position, in font units, of the */
- /* underline line for this face. It is the */
- /* center of the underlining stem. Only */
- /* relevant for scalable formats. */
- /* */
- /* underline_thickness :: The thickness, in font units, of the */
- /* underline for this face. Only relevant for */
- /* scalable formats. */
- /* */
- /* glyph :: The face's associated glyph slot(s). */
- /* */
- /* size :: The current active size for this face. */
- /* */
- /* charmap :: The current active charmap for this face. */
- /* */
- /* <Note> */
- /* Fields may be changed after a call to @FT_Attach_File or */
- /* @FT_Attach_Stream. */
- /* */
- /* For an OpenType variation font, the values of the following fields */
- /* can change after a call to @FT_Set_Var_Design_Coordinates (and */
- /* friends) if the font contains an `MVAR' table: `ascender', */
- /* `descender', `height', `underline_position', and */
- /* `underline_thickness'. */
- /* */
- /* Especially for TrueType fonts see also the documentation for */
- /* @FT_Size_Metrics. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_FaceRec
+ *
+ * @description:
+ * FreeType root face class structure. A face object models a typeface
+ * in a font file.
+ *
+ * @fields:
+ * num_faces ::
+ * The number of faces in the font file. Some font formats can have
+ * multiple faces in a single font file.
+ *
+ * face_index ::
+ * This field holds two different values. Bits 0-15 are the index of
+ * the face in the font file (starting with value~0). They are set
+ * to~0 if there is only one face in the font file.
+ *
+ * [Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation
+ * fonts only, holding the named instance index for the current face
+ * index (starting with value~1; value~0 indicates font access without
+ * a named instance). For non-variation fonts, bits 16-30 are ignored.
+ * If we have the third named instance of face~4, say, `face_index` is
+ * set to 0x00030004.
+ *
+ * Bit 31 is always zero (this is, `face_index` is always a positive
+ * value).
+ *
+ * [Since 2.9] Changing the design coordinates with
+ * @FT_Set_Var_Design_Coordinates or @FT_Set_Var_Blend_Coordinates does
+ * not influence the named instance index value (only
+ * @FT_Set_Named_Instance does that).
+ *
+ * face_flags ::
+ * A set of bit flags that give important information about the face;
+ * see @FT_FACE_FLAG_XXX for the details.
+ *
+ * style_flags ::
+ * The lower 16~bits contain a set of bit flags indicating the style of
+ * the face; see @FT_STYLE_FLAG_XXX for the details.
+ *
+ * [Since 2.6.1] Bits 16-30 hold the number of named instances
+ * available for the current face if we have a GX or OpenType variation
+ * (sub)font. Bit 31 is always zero (this is, `style_flags` is always
+ * a positive value). Note that a variation font has always at least
+ * one named instance, namely the default instance.
+ *
+ * num_glyphs ::
+ * The number of glyphs in the face. If the face is scalable and has
+ * sbits (see `num_fixed_sizes`), it is set to the number of outline
+ * glyphs.
+ *
+ * For CID-keyed fonts (not in an SFNT wrapper) this value gives the
+ * highest CID used in the font.
+ *
+ * family_name ::
+ * The face's family name. This is an ASCII string, usually in
+ * English, that describes the typeface's family (like 'Times New
+ * Roman', 'Bodoni', 'Garamond', etc). This is a least common
+ * denominator used to list fonts. Some formats (TrueType & OpenType)
+ * provide localized and Unicode versions of this string. Applications
+ * should use the format-specific interface to access them. Can be
+ * `NULL` (e.g., in fonts embedded in a PDF file).
+ *
+ * In case the font doesn't provide a specific family name entry,
+ * FreeType tries to synthesize one, deriving it from other name
+ * entries.
+ *
+ * style_name ::
+ * The face's style name. This is an ASCII string, usually in English,
+ * that describes the typeface's style (like 'Italic', 'Bold',
+ * 'Condensed', etc). Not all font formats provide a style name, so
+ * this field is optional, and can be set to `NULL`. As for
+ * `family_name`, some formats provide localized and Unicode versions
+ * of this string. Applications should use the format-specific
+ * interface to access them.
+ *
+ * num_fixed_sizes ::
+ * The number of bitmap strikes in the face. Even if the face is
+ * scalable, there might still be bitmap strikes, which are called
+ * 'sbits' in that case.
+ *
+ * available_sizes ::
+ * An array of @FT_Bitmap_Size for all bitmap strikes in the face. It
+ * is set to `NULL` if there is no bitmap strike.
+ *
+ * Note that FreeType tries to sanitize the strike data since they are
+ * sometimes sloppy or incorrect, but this can easily fail.
+ *
+ * num_charmaps ::
+ * The number of charmaps in the face.
+ *
+ * charmaps ::
+ * An array of the charmaps of the face.
+ *
+ * generic ::
+ * A field reserved for client uses. See the @FT_Generic type
+ * description.
+ *
+ * bbox ::
+ * The font bounding box. Coordinates are expressed in font units (see
+ * `units_per_EM`). The box is large enough to contain any glyph from
+ * the font. Thus, `bbox.yMax` can be seen as the 'maximum ascender',
+ * and `bbox.yMin` as the 'minimum descender'. Only relevant for
+ * scalable formats.
+ *
+ * Note that the bounding box might be off by (at least) one pixel for
+ * hinted fonts. See @FT_Size_Metrics for further discussion.
+ *
+ * units_per_EM ::
+ * The number of font units per EM square for this face. This is
+ * typically 2048 for TrueType fonts, and 1000 for Type~1 fonts. Only
+ * relevant for scalable formats.
+ *
+ * ascender ::
+ * The typographic ascender of the face, expressed in font units. For
+ * font formats not having this information, it is set to `bbox.yMax`.
+ * Only relevant for scalable formats.
+ *
+ * descender ::
+ * The typographic descender of the face, expressed in font units. For
+ * font formats not having this information, it is set to `bbox.yMin`.
+ * Note that this field is negative for values below the baseline.
+ * Only relevant for scalable formats.
+ *
+ * height ::
+ * This value is the vertical distance between two consecutive
+ * baselines, expressed in font units. It is always positive. Only
+ * relevant for scalable formats.
+ *
+ * If you want the global glyph height, use `ascender - descender`.
+ *
+ * max_advance_width ::
+ * The maximum advance width, in font units, for all glyphs in this
+ * face. This can be used to make word wrapping computations faster.
+ * Only relevant for scalable formats.
+ *
+ * max_advance_height ::
+ * The maximum advance height, in font units, for all glyphs in this
+ * face. This is only relevant for vertical layouts, and is set to
+ * `height` for fonts that do not provide vertical metrics. Only
+ * relevant for scalable formats.
+ *
+ * underline_position ::
+ * The position, in font units, of the underline line for this face.
+ * It is the center of the underlining stem. Only relevant for
+ * scalable formats.
+ *
+ * underline_thickness ::
+ * The thickness, in font units, of the underline for this face. Only
+ * relevant for scalable formats.
+ *
+ * glyph ::
+ * The face's associated glyph slot(s).
+ *
+ * size ::
+ * The current active size for this face.
+ *
+ * charmap ::
+ * The current active charmap for this face.
+ *
+ * @note:
+ * Fields may be changed after a call to @FT_Attach_File or
+ * @FT_Attach_Stream.
+ *
+ * For an OpenType variation font, the values of the following fields can
+ * change after a call to @FT_Set_Var_Design_Coordinates (and friends) if
+ * the font contains an 'MVAR' table: `ascender`, `descender`, `height`,
+ * `underline_position`, and `underline_thickness`.
+ *
+ * Especially for TrueType fonts see also the documentation for
+ * @FT_Size_Metrics.
+ */
typedef struct FT_FaceRec_
{
FT_Long num_faces;
@@ -1087,7 +1059,7 @@ FT_BEGIN_HEADER
FT_Generic generic;
- /*# The following member variables (down to `underline_thickness') */
+ /*# The following member variables (down to `underline_thickness`) */
/*# are only relevant to scalable outlines; cf. @FT_Bitmap_Size */
/*# for bitmap fonts. */
FT_BBox bbox;
@@ -1125,117 +1097,116 @@ FT_BEGIN_HEADER
} FT_FaceRec;
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* FT_FACE_FLAG_XXX */
- /* */
- /* <Description> */
- /* A list of bit flags used in the `face_flags' field of the */
- /* @FT_FaceRec structure. They inform client applications of */
- /* properties of the corresponding face. */
- /* */
- /* <Values> */
- /* FT_FACE_FLAG_SCALABLE :: */
- /* The face contains outline glyphs. Note that a face can contain */
- /* bitmap strikes also, i.e., a face can have both this flag and */
- /* @FT_FACE_FLAG_FIXED_SIZES set. */
- /* */
- /* FT_FACE_FLAG_FIXED_SIZES :: */
- /* The face contains bitmap strikes. See also the */
- /* `num_fixed_sizes' and `available_sizes' fields of @FT_FaceRec. */
- /* */
- /* FT_FACE_FLAG_FIXED_WIDTH :: */
- /* The face contains fixed-width characters (like Courier, Lucida, */
- /* MonoType, etc.). */
- /* */
- /* FT_FACE_FLAG_SFNT :: */
- /* The face uses the SFNT storage scheme. For now, this means */
- /* TrueType and OpenType. */
- /* */
- /* FT_FACE_FLAG_HORIZONTAL :: */
- /* The face contains horizontal glyph metrics. This should be set */
- /* for all common formats. */
- /* */
- /* FT_FACE_FLAG_VERTICAL :: */
- /* The face contains vertical glyph metrics. This is only */
- /* available in some formats, not all of them. */
- /* */
- /* FT_FACE_FLAG_KERNING :: */
- /* The face contains kerning information. If set, the kerning */
- /* distance can be retrieved using the function @FT_Get_Kerning. */
- /* Otherwise the function always return the vector (0,0). Note */
- /* that FreeType doesn't handle kerning data from the SFNT `GPOS' */
- /* table (as present in many OpenType fonts). */
- /* */
- /* FT_FACE_FLAG_FAST_GLYPHS :: */
- /* THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT. */
- /* */
- /* FT_FACE_FLAG_MULTIPLE_MASTERS :: */
- /* The face contains multiple masters and is capable of */
- /* interpolating between them. Supported formats are Adobe MM, */
- /* TrueType GX, and OpenType variation fonts. */
- /* */
- /* See section @multiple_masters for API details. */
- /* */
- /* FT_FACE_FLAG_GLYPH_NAMES :: */
- /* The face contains glyph names, which can be retrieved using */
- /* @FT_Get_Glyph_Name. Note that some TrueType fonts contain */
- /* broken glyph name tables. Use the function */
- /* @FT_Has_PS_Glyph_Names when needed. */
- /* */
- /* FT_FACE_FLAG_EXTERNAL_STREAM :: */
- /* Used internally by FreeType to indicate that a face's stream was */
- /* provided by the client application and should not be destroyed */
- /* when @FT_Done_Face is called. Don't read or test this flag. */
- /* */
- /* FT_FACE_FLAG_HINTER :: */
- /* The font driver has a hinting machine of its own. For example, */
- /* with TrueType fonts, it makes sense to use data from the SFNT */
- /* `gasp' table only if the native TrueType hinting engine (with */
- /* the bytecode interpreter) is available and active. */
- /* */
- /* FT_FACE_FLAG_CID_KEYED :: */
- /* The face is CID-keyed. In that case, the face is not accessed */
- /* by glyph indices but by CID values. For subsetted CID-keyed */
- /* fonts this has the consequence that not all index values are a */
- /* valid argument to @FT_Load_Glyph. Only the CID values for which */
- /* corresponding glyphs in the subsetted font exist make */
- /* `FT_Load_Glyph' return successfully; in all other cases you get */
- /* an `FT_Err_Invalid_Argument' error. */
- /* */
- /* Note that CID-keyed fonts that are in an SFNT wrapper (this is, */
- /* all OpenType/CFF fonts) don't have this flag set since the */
- /* glyphs are accessed in the normal way (using contiguous */
- /* indices); the `CID-ness' isn't visible to the application. */
- /* */
- /* FT_FACE_FLAG_TRICKY :: */
- /* The face is `tricky', this is, it always needs the font format's */
- /* native hinting engine to get a reasonable result. A typical */
- /* example is the old Chinese font `mingli.ttf' (but not */
- /* `mingliu.ttc') that uses TrueType bytecode instructions to move */
- /* and scale all of its subglyphs. */
- /* */
- /* It is not possible to auto-hint such fonts using */
- /* @FT_LOAD_FORCE_AUTOHINT; it will also ignore */
- /* @FT_LOAD_NO_HINTING. You have to set both @FT_LOAD_NO_HINTING */
- /* and @FT_LOAD_NO_AUTOHINT to really disable hinting; however, you */
- /* probably never want this except for demonstration purposes. */
- /* */
- /* Currently, there are about a dozen TrueType fonts in the list of */
- /* tricky fonts; they are hard-coded in file `ttobjs.c'. */
- /* */
- /* FT_FACE_FLAG_COLOR :: */
- /* [Since 2.5.1] The face has color glyph tables. To access color */
- /* glyphs use @FT_LOAD_COLOR. */
- /* */
- /* FT_FACE_FLAG_VARIATION :: */
- /* [Since 2.9] Set if the current face (or named instance) has been */
- /* altered with @FT_Set_MM_Design_Coordinates, */
- /* @FT_Set_Var_Design_Coordinates, or */
- /* @FT_Set_Var_Blend_Coordinates. This flag is unset by a call to */
- /* @FT_Set_Named_Instance. */
- /* */
+ /**************************************************************************
+ *
+ * @enum:
+ * FT_FACE_FLAG_XXX
+ *
+ * @description:
+ * A list of bit flags used in the `face_flags` field of the @FT_FaceRec
+ * structure. They inform client applications of properties of the
+ * corresponding face.
+ *
+ * @values:
+ * FT_FACE_FLAG_SCALABLE ::
+ * The face contains outline glyphs. Note that a face can contain
+ * bitmap strikes also, i.e., a face can have both this flag and
+ * @FT_FACE_FLAG_FIXED_SIZES set.
+ *
+ * FT_FACE_FLAG_FIXED_SIZES ::
+ * The face contains bitmap strikes. See also the `num_fixed_sizes`
+ * and `available_sizes` fields of @FT_FaceRec.
+ *
+ * FT_FACE_FLAG_FIXED_WIDTH ::
+ * The face contains fixed-width characters (like Courier, Lucida,
+ * MonoType, etc.).
+ *
+ * FT_FACE_FLAG_SFNT ::
+ * The face uses the SFNT storage scheme. For now, this means TrueType
+ * and OpenType.
+ *
+ * FT_FACE_FLAG_HORIZONTAL ::
+ * The face contains horizontal glyph metrics. This should be set for
+ * all common formats.
+ *
+ * FT_FACE_FLAG_VERTICAL ::
+ * The face contains vertical glyph metrics. This is only available in
+ * some formats, not all of them.
+ *
+ * FT_FACE_FLAG_KERNING ::
+ * The face contains kerning information. If set, the kerning distance
+ * can be retrieved using the function @FT_Get_Kerning. Otherwise the
+ * function always return the vector (0,0). Note that FreeType doesn't
+ * handle kerning data from the SFNT 'GPOS' table (as present in many
+ * OpenType fonts).
+ *
+ * FT_FACE_FLAG_FAST_GLYPHS ::
+ * THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT.
+ *
+ * FT_FACE_FLAG_MULTIPLE_MASTERS ::
+ * The face contains multiple masters and is capable of interpolating
+ * between them. Supported formats are Adobe MM, TrueType GX, and
+ * OpenType variation fonts.
+ *
+ * See section @multiple_masters for API details.
+ *
+ * FT_FACE_FLAG_GLYPH_NAMES ::
+ * The face contains glyph names, which can be retrieved using
+ * @FT_Get_Glyph_Name. Note that some TrueType fonts contain broken
+ * glyph name tables. Use the function @FT_Has_PS_Glyph_Names when
+ * needed.
+ *
+ * FT_FACE_FLAG_EXTERNAL_STREAM ::
+ * Used internally by FreeType to indicate that a face's stream was
+ * provided by the client application and should not be destroyed when
+ * @FT_Done_Face is called. Don't read or test this flag.
+ *
+ * FT_FACE_FLAG_HINTER ::
+ * The font driver has a hinting machine of its own. For example, with
+ * TrueType fonts, it makes sense to use data from the SFNT 'gasp'
+ * table only if the native TrueType hinting engine (with the bytecode
+ * interpreter) is available and active.
+ *
+ * FT_FACE_FLAG_CID_KEYED ::
+ * The face is CID-keyed. In that case, the face is not accessed by
+ * glyph indices but by CID values. For subsetted CID-keyed fonts this
+ * has the consequence that not all index values are a valid argument
+ * to @FT_Load_Glyph. Only the CID values for which corresponding
+ * glyphs in the subsetted font exist make `FT_Load_Glyph` return
+ * successfully; in all other cases you get an
+ * `FT_Err_Invalid_Argument` error.
+ *
+ * Note that CID-keyed fonts that are in an SFNT wrapper (this is, all
+ * OpenType/CFF fonts) don't have this flag set since the glyphs are
+ * accessed in the normal way (using contiguous indices); the
+ * 'CID-ness' isn't visible to the application.
+ *
+ * FT_FACE_FLAG_TRICKY ::
+ * The face is 'tricky', this is, it always needs the font format's
+ * native hinting engine to get a reasonable result. A typical example
+ * is the old Chinese font `mingli.ttf` (but not `mingliu.ttc`) that
+ * uses TrueType bytecode instructions to move and scale all of its
+ * subglyphs.
+ *
+ * It is not possible to auto-hint such fonts using
+ * @FT_LOAD_FORCE_AUTOHINT; it will also ignore @FT_LOAD_NO_HINTING.
+ * You have to set both @FT_LOAD_NO_HINTING and @FT_LOAD_NO_AUTOHINT to
+ * really disable hinting; however, you probably never want this except
+ * for demonstration purposes.
+ *
+ * Currently, there are about a dozen TrueType fonts in the list of
+ * tricky fonts; they are hard-coded in file `ttobjs.c`.
+ *
+ * FT_FACE_FLAG_COLOR ::
+ * [Since 2.5.1] The face has color glyph tables. See @FT_LOAD_COLOR
+ * for more information.
+ *
+ * FT_FACE_FLAG_VARIATION ::
+ * [Since 2.9] Set if the current face (or named instance) has been
+ * altered with @FT_Set_MM_Design_Coordinates,
+ * @FT_Set_Var_Design_Coordinates, or @FT_Set_Var_Blend_Coordinates.
+ * This flag is unset by a call to @FT_Set_Named_Instance.
+ */
#define FT_FACE_FLAG_SCALABLE ( 1L << 0 )
#define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 )
#define FT_FACE_FLAG_FIXED_WIDTH ( 1L << 2 )
@@ -1254,14 +1225,14 @@ FT_BEGIN_HEADER
#define FT_FACE_FLAG_VARIATION ( 1L << 15 )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_HAS_HORIZONTAL( face )
+ * FT_HAS_HORIZONTAL
*
* @description:
- * A macro that returns true whenever a face object contains
- * horizontal metrics (this is true for all font formats though).
+ * A macro that returns true whenever a face object contains horizontal
+ * metrics (this is true for all font formats though).
*
* @also:
* @FT_HAS_VERTICAL can be used to check for vertical metrics.
@@ -1271,10 +1242,10 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_HORIZONTAL )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_HAS_VERTICAL( face )
+ * FT_HAS_VERTICAL
*
* @description:
* A macro that returns true whenever a face object contains real
@@ -1285,45 +1256,45 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_VERTICAL )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_HAS_KERNING( face )
+ * FT_HAS_KERNING
*
* @description:
- * A macro that returns true whenever a face object contains kerning
- * data that can be accessed with @FT_Get_Kerning.
+ * A macro that returns true whenever a face object contains kerning data
+ * that can be accessed with @FT_Get_Kerning.
*
*/
#define FT_HAS_KERNING( face ) \
( (face)->face_flags & FT_FACE_FLAG_KERNING )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_IS_SCALABLE( face )
+ * FT_IS_SCALABLE
*
* @description:
* A macro that returns true whenever a face object contains a scalable
- * font face (true for TrueType, Type~1, Type~42, CID, OpenType/CFF,
- * and PFR font formats).
+ * font face (true for TrueType, Type~1, Type~42, CID, OpenType/CFF, and
+ * PFR font formats).
*
*/
#define FT_IS_SCALABLE( face ) \
( (face)->face_flags & FT_FACE_FLAG_SCALABLE )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_IS_SFNT( face )
+ * FT_IS_SFNT
*
* @description:
- * A macro that returns true whenever a face object contains a font
- * whose format is based on the SFNT storage scheme. This usually
- * means: TrueType fonts, OpenType fonts, as well as SFNT-based embedded
- * bitmap fonts.
+ * A macro that returns true whenever a face object contains a font whose
+ * format is based on the SFNT storage scheme. This usually means:
+ * TrueType fonts, OpenType fonts, as well as SFNT-based embedded bitmap
+ * fonts.
*
* If this macro is true, all functions defined in @FT_SFNT_NAMES_H and
* @FT_TRUETYPE_TABLES_H are available.
@@ -1333,14 +1304,14 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_SFNT )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_IS_FIXED_WIDTH( face )
+ * FT_IS_FIXED_WIDTH
*
* @description:
* A macro that returns true whenever a face object contains a font face
- * that contains fixed-width (or `monospace', `fixed-pitch', etc.)
+ * that contains fixed-width (or 'monospace', 'fixed-pitch', etc.)
* glyphs.
*
*/
@@ -1348,25 +1319,25 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_FIXED_WIDTH )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_HAS_FIXED_SIZES( face )
+ * FT_HAS_FIXED_SIZES
*
* @description:
* A macro that returns true whenever a face object contains some
- * embedded bitmaps. See the `available_sizes' field of the
- * @FT_FaceRec structure.
+ * embedded bitmaps. See the `available_sizes` field of the @FT_FaceRec
+ * structure.
*
*/
#define FT_HAS_FIXED_SIZES( face ) \
( (face)->face_flags & FT_FACE_FLAG_FIXED_SIZES )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_HAS_FAST_GLYPHS( face )
+ * FT_HAS_FAST_GLYPHS
*
* @description:
* Deprecated.
@@ -1375,10 +1346,10 @@ FT_BEGIN_HEADER
#define FT_HAS_FAST_GLYPHS( face ) 0
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_HAS_GLYPH_NAMES( face )
+ * FT_HAS_GLYPH_NAMES
*
* @description:
* A macro that returns true whenever a face object contains some glyph
@@ -1389,10 +1360,10 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_GLYPH_NAMES )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_HAS_MULTIPLE_MASTERS( face )
+ * FT_HAS_MULTIPLE_MASTERS
*
* @description:
* A macro that returns true whenever a face object contains some
@@ -1404,10 +1375,10 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_MULTIPLE_MASTERS )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_IS_NAMED_INSTANCE( face )
+ * FT_IS_NAMED_INSTANCE
*
* @description:
* A macro that returns true whenever a face object is a named instance
@@ -1426,14 +1397,14 @@ FT_BEGIN_HEADER
( (face)->face_index & 0x7FFF0000L )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_IS_VARIATION( face )
+ * FT_IS_VARIATION
*
* @description:
- * A macro that returns true whenever a face object has been altered
- * by @FT_Set_MM_Design_Coordinates, @FT_Set_Var_Design_Coordinates, or
+ * A macro that returns true whenever a face object has been altered by
+ * @FT_Set_MM_Design_Coordinates, @FT_Set_Var_Design_Coordinates, or
* @FT_Set_Var_Blend_Coordinates.
*
* @since:
@@ -1444,15 +1415,14 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_VARIATION )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_IS_CID_KEYED( face )
+ * FT_IS_CID_KEYED
*
* @description:
* A macro that returns true whenever a face object contains a CID-keyed
- * font. See the discussion of @FT_FACE_FLAG_CID_KEYED for more
- * details.
+ * font. See the discussion of @FT_FACE_FLAG_CID_KEYED for more details.
*
* If this macro is true, all functions defined in @FT_CID_H are
* available.
@@ -1462,13 +1432,13 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_CID_KEYED )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_IS_TRICKY( face )
+ * FT_IS_TRICKY
*
* @description:
- * A macro that returns true whenever a face represents a `tricky' font.
+ * A macro that returns true whenever a face represents a 'tricky' font.
* See the discussion of @FT_FACE_FLAG_TRICKY for more details.
*
*/
@@ -1476,14 +1446,14 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_TRICKY )
- /*************************************************************************
+ /**************************************************************************
*
* @macro:
- * FT_HAS_COLOR( face )
+ * FT_HAS_COLOR
*
* @description:
- * A macro that returns true whenever a face object contains
- * tables for color glyphs.
+ * A macro that returns true whenever a face object contains tables for
+ * color glyphs.
*
* @since:
* 2.5.1
@@ -1493,149 +1463,148 @@ FT_BEGIN_HEADER
( (face)->face_flags & FT_FACE_FLAG_COLOR )
- /*************************************************************************/
- /* */
- /* <Const> */
- /* FT_STYLE_FLAG_XXX */
- /* */
- /* <Description> */
- /* A list of bit flags to indicate the style of a given face. These */
- /* are used in the `style_flags' field of @FT_FaceRec. */
- /* */
- /* <Values> */
- /* FT_STYLE_FLAG_ITALIC :: */
- /* The face style is italic or oblique. */
- /* */
- /* FT_STYLE_FLAG_BOLD :: */
- /* The face is bold. */
- /* */
- /* <Note> */
- /* The style information as provided by FreeType is very basic. More */
- /* details are beyond the scope and should be done on a higher level */
- /* (for example, by analyzing various fields of the `OS/2' table in */
- /* SFNT based fonts). */
- /* */
+ /**************************************************************************
+ *
+ * @enum:
+ * FT_STYLE_FLAG_XXX
+ *
+ * @description:
+ * A list of bit flags to indicate the style of a given face. These are
+ * used in the `style_flags` field of @FT_FaceRec.
+ *
+ * @values:
+ * FT_STYLE_FLAG_ITALIC ::
+ * The face style is italic or oblique.
+ *
+ * FT_STYLE_FLAG_BOLD ::
+ * The face is bold.
+ *
+ * @note:
+ * The style information as provided by FreeType is very basic. More
+ * details are beyond the scope and should be done on a higher level (for
+ * example, by analyzing various fields of the 'OS/2' table in SFNT based
+ * fonts).
+ */
#define FT_STYLE_FLAG_ITALIC ( 1 << 0 )
#define FT_STYLE_FLAG_BOLD ( 1 << 1 )
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Size_Internal */
- /* */
- /* <Description> */
- /* An opaque handle to an `FT_Size_InternalRec' structure, used to */
- /* model private data of a given @FT_Size object. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Size_Internal
+ *
+ * @description:
+ * An opaque handle to an `FT_Size_InternalRec` structure, used to model
+ * private data of a given @FT_Size object.
+ */
typedef struct FT_Size_InternalRec_* FT_Size_Internal;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_Size_Metrics */
- /* */
- /* <Description> */
- /* The size metrics structure gives the metrics of a size object. */
- /* */
- /* <Fields> */
- /* x_ppem :: The width of the scaled EM square in pixels, hence */
- /* the term `ppem' (pixels per EM). It is also */
- /* referred to as `nominal width'. */
- /* */
- /* y_ppem :: The height of the scaled EM square in pixels, */
- /* hence the term `ppem' (pixels per EM). It is also */
- /* referred to as `nominal height'. */
- /* */
- /* x_scale :: A 16.16 fractional scaling value to convert */
- /* horizontal metrics from font units to 26.6 */
- /* fractional pixels. Only relevant for scalable */
- /* font formats. */
- /* */
- /* y_scale :: A 16.16 fractional scaling value to convert */
- /* vertical metrics from font units to 26.6 */
- /* fractional pixels. Only relevant for scalable */
- /* font formats. */
- /* */
- /* ascender :: The ascender in 26.6 fractional pixels, rounded up */
- /* to an integer value. See @FT_FaceRec for the */
- /* details. */
- /* */
- /* descender :: The descender in 26.6 fractional pixels, rounded */
- /* down to an integer value. See @FT_FaceRec for the */
- /* details. */
- /* */
- /* height :: The height in 26.6 fractional pixels, rounded to */
- /* an integer value. See @FT_FaceRec for the */
- /* details. */
- /* */
- /* max_advance :: The maximum advance width in 26.6 fractional */
- /* pixels, rounded to an integer value. See */
- /* @FT_FaceRec for the details. */
- /* */
- /* <Note> */
- /* The scaling values, if relevant, are determined first during a */
- /* size changing operation. The remaining fields are then set by the */
- /* driver. For scalable formats, they are usually set to scaled */
- /* values of the corresponding fields in @FT_FaceRec. Some values */
- /* like ascender or descender are rounded for historical reasons; */
- /* more precise values (for outline fonts) can be derived by scaling */
- /* the corresponding @FT_FaceRec values manually, with code similar */
- /* to the following. */
- /* */
- /* { */
- /* scaled_ascender = FT_MulFix( face->ascender, */
- /* size_metrics->y_scale ); */
- /* } */
- /* */
- /* Note that due to glyph hinting and the selected rendering mode */
- /* these values are usually not exact; consequently, they must be */
- /* treated as unreliable with an error margin of at least one pixel! */
- /* */
- /* Indeed, the only way to get the exact metrics is to render _all_ */
- /* glyphs. As this would be a definite performance hit, it is up to */
- /* client applications to perform such computations. */
- /* */
- /* The `FT_Size_Metrics' structure is valid for bitmap fonts also. */
- /* */
- /* */
- /* *TrueType* *fonts* *with* *native* *bytecode* *hinting* */
- /* */
- /* All applications that handle TrueType fonts with native hinting */
- /* must be aware that TTFs expect different rounding of vertical font */
- /* dimensions. The application has to cater for this, especially if */
- /* it wants to rely on a TTF's vertical data (for example, to */
- /* properly align box characters vertically). */
- /* */
- /* Only the application knows _in_ _advance_ that it is going to use */
- /* native hinting for TTFs! FreeType, on the other hand, selects the */
- /* hinting mode not at the time of creating an @FT_Size object but */
- /* much later, namely while calling @FT_Load_Glyph. */
- /* */
- /* Here is some pseudo code that illustrates a possible solution. */
- /* */
- /* { */
- /* font_format = FT_Get_Font_Format( face ); */
- /* */
- /* if ( !strcmp( font_format, "TrueType" ) && */
- /* do_native_bytecode_hinting ) */
- /* { */
- /* ascender = ROUND( FT_MulFix( face->ascender, */
- /* size_metrics->y_scale ) ); */
- /* descender = ROUND( FT_MulFix( face->descender, */
- /* size_metrics->y_scale ) ); */
- /* } */
- /* else */
- /* { */
- /* ascender = size_metrics->ascender; */
- /* descender = size_metrics->descender; */
- /* } */
- /* */
- /* height = size_metrics->height; */
- /* max_advance = size_metrics->max_advance; */
- /* } */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_Size_Metrics
+ *
+ * @description:
+ * The size metrics structure gives the metrics of a size object.
+ *
+ * @fields:
+ * x_ppem ::
+ * The width of the scaled EM square in pixels, hence the term 'ppem'
+ * (pixels per EM). It is also referred to as 'nominal width'.
+ *
+ * y_ppem ::
+ * The height of the scaled EM square in pixels, hence the term 'ppem'
+ * (pixels per EM). It is also referred to as 'nominal height'.
+ *
+ * x_scale ::
+ * A 16.16 fractional scaling value to convert horizontal metrics from
+ * font units to 26.6 fractional pixels. Only relevant for scalable
+ * font formats.
+ *
+ * y_scale ::
+ * A 16.16 fractional scaling value to convert vertical metrics from
+ * font units to 26.6 fractional pixels. Only relevant for scalable
+ * font formats.
+ *
+ * ascender ::
+ * The ascender in 26.6 fractional pixels, rounded up to an integer
+ * value. See @FT_FaceRec for the details.
+ *
+ * descender ::
+ * The descender in 26.6 fractional pixels, rounded down to an integer
+ * value. See @FT_FaceRec for the details.
+ *
+ * height ::
+ * The height in 26.6 fractional pixels, rounded to an integer value.
+ * See @FT_FaceRec for the details.
+ *
+ * max_advance ::
+ * The maximum advance width in 26.6 fractional pixels, rounded to an
+ * integer value. See @FT_FaceRec for the details.
+ *
+ * @note:
+ * The scaling values, if relevant, are determined first during a size
+ * changing operation. The remaining fields are then set by the driver.
+ * For scalable formats, they are usually set to scaled values of the
+ * corresponding fields in @FT_FaceRec. Some values like ascender or
+ * descender are rounded for historical reasons; more precise values (for
+ * outline fonts) can be derived by scaling the corresponding @FT_FaceRec
+ * values manually, with code similar to the following.
+ *
+ * ```
+ * scaled_ascender = FT_MulFix( face->ascender,
+ * size_metrics->y_scale );
+ * ```
+ *
+ * Note that due to glyph hinting and the selected rendering mode these
+ * values are usually not exact; consequently, they must be treated as
+ * unreliable with an error margin of at least one pixel!
+ *
+ * Indeed, the only way to get the exact metrics is to render _all_
+ * glyphs. As this would be a definite performance hit, it is up to
+ * client applications to perform such computations.
+ *
+ * The `FT_Size_Metrics` structure is valid for bitmap fonts also.
+ *
+ *
+ * **TrueType fonts with native bytecode hinting**
+ *
+ * All applications that handle TrueType fonts with native hinting must
+ * be aware that TTFs expect different rounding of vertical font
+ * dimensions. The application has to cater for this, especially if it
+ * wants to rely on a TTF's vertical data (for example, to properly align
+ * box characters vertically).
+ *
+ * Only the application knows _in advance_ that it is going to use native
+ * hinting for TTFs! FreeType, on the other hand, selects the hinting
+ * mode not at the time of creating an @FT_Size object but much later,
+ * namely while calling @FT_Load_Glyph.
+ *
+ * Here is some pseudo code that illustrates a possible solution.
+ *
+ * ```
+ * font_format = FT_Get_Font_Format( face );
+ *
+ * if ( !strcmp( font_format, "TrueType" ) &&
+ * do_native_bytecode_hinting )
+ * {
+ * ascender = ROUND( FT_MulFix( face->ascender,
+ * size_metrics->y_scale ) );
+ * descender = ROUND( FT_MulFix( face->descender,
+ * size_metrics->y_scale ) );
+ * }
+ * else
+ * {
+ * ascender = size_metrics->ascender;
+ * descender = size_metrics->descender;
+ * }
+ *
+ * height = size_metrics->height;
+ * max_advance = size_metrics->max_advance;
+ * ```
+ */
typedef struct FT_Size_Metrics_
{
FT_UShort x_ppem; /* horizontal pixels per EM */
@@ -1652,25 +1621,27 @@ FT_BEGIN_HEADER
} FT_Size_Metrics;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_SizeRec */
- /* */
- /* <Description> */
- /* FreeType root size class structure. A size object models a face */
- /* object at a given size. */
- /* */
- /* <Fields> */
- /* face :: Handle to the parent face object. */
- /* */
- /* generic :: A typeless pointer, unused by the FreeType library or */
- /* any of its drivers. It can be used by client */
- /* applications to link their own data to each size */
- /* object. */
- /* */
- /* metrics :: Metrics for this size object. This field is read-only. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_SizeRec
+ *
+ * @description:
+ * FreeType root size class structure. A size object models a face
+ * object at a given size.
+ *
+ * @fields:
+ * face ::
+ * Handle to the parent face object.
+ *
+ * generic ::
+ * A typeless pointer, unused by the FreeType library or any of its
+ * drivers. It can be used by client applications to link their own
+ * data to each size object.
+ *
+ * metrics ::
+ * Metrics for this size object. This field is read-only.
+ */
typedef struct FT_SizeRec_
{
FT_Face face; /* parent face object */
@@ -1681,237 +1652,241 @@ FT_BEGIN_HEADER
} FT_SizeRec;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_SubGlyph */
- /* */
- /* <Description> */
- /* The subglyph structure is an internal object used to describe */
- /* subglyphs (for example, in the case of composites). */
- /* */
- /* <Note> */
- /* The subglyph implementation is not part of the high-level API, */
- /* hence the forward structure declaration. */
- /* */
- /* You can however retrieve subglyph information with */
- /* @FT_Get_SubGlyph_Info. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_SubGlyph
+ *
+ * @description:
+ * The subglyph structure is an internal object used to describe
+ * subglyphs (for example, in the case of composites).
+ *
+ * @note:
+ * The subglyph implementation is not part of the high-level API, hence
+ * the forward structure declaration.
+ *
+ * You can however retrieve subglyph information with
+ * @FT_Get_SubGlyph_Info.
+ */
typedef struct FT_SubGlyphRec_* FT_SubGlyph;
- /*************************************************************************/
- /* */
- /* <Type> */
- /* FT_Slot_Internal */
- /* */
- /* <Description> */
- /* An opaque handle to an `FT_Slot_InternalRec' structure, used to */
- /* model private data of a given @FT_GlyphSlot object. */
- /* */
+ /**************************************************************************
+ *
+ * @type:
+ * FT_Slot_Internal
+ *
+ * @description:
+ * An opaque handle to an `FT_Slot_InternalRec` structure, used to model
+ * private data of a given @FT_GlyphSlot object.
+ */
typedef struct FT_Slot_InternalRec_* FT_Slot_Internal;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_GlyphSlotRec */
- /* */
- /* <Description> */
- /* FreeType root glyph slot class structure. A glyph slot is a */
- /* container where individual glyphs can be loaded, be they in */
- /* outline or bitmap format. */
- /* */
- /* <Fields> */
- /* library :: A handle to the FreeType library instance */
- /* this slot belongs to. */
- /* */
- /* face :: A handle to the parent face object. */
- /* */
- /* next :: In some cases (like some font tools), several */
- /* glyph slots per face object can be a good */
- /* thing. As this is rare, the glyph slots are */
- /* listed through a direct, single-linked list */
- /* using its `next' field. */
- /* */
- /* generic :: A typeless pointer unused by the FreeType */
- /* library or any of its drivers. It can be */
- /* used by client applications to link their own */
- /* data to each glyph slot object. */
- /* */
- /* metrics :: The metrics of the last loaded glyph in the */
- /* slot. The returned values depend on the last */
- /* load flags (see the @FT_Load_Glyph API */
- /* function) and can be expressed either in 26.6 */
- /* fractional pixels or font units. */
- /* */
- /* Note that even when the glyph image is */
- /* transformed, the metrics are not. */
- /* */
- /* linearHoriAdvance :: The advance width of the unhinted glyph. */
- /* Its value is expressed in 16.16 fractional */
- /* pixels, unless @FT_LOAD_LINEAR_DESIGN is set */
- /* when loading the glyph. This field can be */
- /* important to perform correct WYSIWYG layout. */
- /* Only relevant for outline glyphs. */
- /* */
- /* linearVertAdvance :: The advance height of the unhinted glyph. */
- /* Its value is expressed in 16.16 fractional */
- /* pixels, unless @FT_LOAD_LINEAR_DESIGN is set */
- /* when loading the glyph. This field can be */
- /* important to perform correct WYSIWYG layout. */
- /* Only relevant for outline glyphs. */
- /* */
- /* advance :: This shorthand is, depending on */
- /* @FT_LOAD_IGNORE_TRANSFORM, the transformed */
- /* (hinted) advance width for the glyph, in 26.6 */
- /* fractional pixel format. As specified with */
- /* @FT_LOAD_VERTICAL_LAYOUT, it uses either the */
- /* `horiAdvance' or the `vertAdvance' value of */
- /* `metrics' field. */
- /* */
- /* format :: This field indicates the format of the image */
- /* contained in the glyph slot. Typically */
- /* @FT_GLYPH_FORMAT_BITMAP, */
- /* @FT_GLYPH_FORMAT_OUTLINE, or */
- /* @FT_GLYPH_FORMAT_COMPOSITE, but other values */
- /* are possible. */
- /* */
- /* bitmap :: This field is used as a bitmap descriptor. */
- /* Note that the address and content of the */
- /* bitmap buffer can change between calls of */
- /* @FT_Load_Glyph and a few other functions. */
- /* */
- /* bitmap_left :: The bitmap's left bearing expressed in */
- /* integer pixels. */
- /* */
- /* bitmap_top :: The bitmap's top bearing expressed in integer */
- /* pixels. This is the distance from the */
- /* baseline to the top-most glyph scanline, */
- /* upwards y~coordinates being *positive*. */
- /* */
- /* outline :: The outline descriptor for the current glyph */
- /* image if its format is */
- /* @FT_GLYPH_FORMAT_OUTLINE. Once a glyph is */
- /* loaded, `outline' can be transformed, */
- /* distorted, emboldened, etc. However, it must */
- /* not be freed. */
- /* */
- /* num_subglyphs :: The number of subglyphs in a composite glyph. */
- /* This field is only valid for the composite */
- /* glyph format that should normally only be */
- /* loaded with the @FT_LOAD_NO_RECURSE flag. */
- /* */
- /* subglyphs :: An array of subglyph descriptors for */
- /* composite glyphs. There are `num_subglyphs' */
- /* elements in there. Currently internal to */
- /* FreeType. */
- /* */
- /* control_data :: Certain font drivers can also return the */
- /* control data for a given glyph image (e.g. */
- /* TrueType bytecode, Type~1 charstrings, etc.). */
- /* This field is a pointer to such data; it is */
- /* currently internal to FreeType. */
- /* */
- /* control_len :: This is the length in bytes of the control */
- /* data. Currently internal to FreeType. */
- /* */
- /* other :: Reserved. */
- /* */
- /* lsb_delta :: The difference between hinted and unhinted */
- /* left side bearing while auto-hinting is */
- /* active. Zero otherwise. */
- /* */
- /* rsb_delta :: The difference between hinted and unhinted */
- /* right side bearing while auto-hinting is */
- /* active. Zero otherwise. */
- /* */
- /* <Note> */
- /* If @FT_Load_Glyph is called with default flags (see */
- /* @FT_LOAD_DEFAULT) the glyph image is loaded in the glyph slot in */
- /* its native format (e.g., an outline glyph for TrueType and Type~1 */
- /* formats). [Since 2.9] The prospective bitmap metrics are */
- /* calculated according to @FT_LOAD_TARGET_XXX and other flags even */
- /* for the outline glyph, even if @FT_LOAD_RENDER is not set. */
- /* */
- /* This image can later be converted into a bitmap by calling */
- /* @FT_Render_Glyph. This function searches the current renderer for */
- /* the native image's format, then invokes it. */
- /* */
- /* The renderer is in charge of transforming the native image through */
- /* the slot's face transformation fields, then converting it into a */
- /* bitmap that is returned in `slot->bitmap'. */
- /* */
- /* Note that `slot->bitmap_left' and `slot->bitmap_top' are also used */
- /* to specify the position of the bitmap relative to the current pen */
- /* position (e.g., coordinates (0,0) on the baseline). Of course, */
- /* `slot->format' is also changed to @FT_GLYPH_FORMAT_BITMAP. */
- /* */
- /* Here is a small pseudo code fragment that shows how to use */
- /* `lsb_delta' and `rsb_delta' to do fractional positioning of */
- /* glyphs: */
- /* */
- /* { */
- /* FT_GlyphSlot slot = face->glyph; */
- /* FT_Pos origin_x = 0; */
- /* */
- /* */
- /* for all glyphs do */
- /* <load glyph with `FT_Load_Glyph'> */
- /* */
- /* FT_Outline_Translate( slot->outline, origin_x & 63, 0 ); */
- /* */
- /* <save glyph image, or render glyph, or ...> */
- /* */
- /* <compute kern between current and next glyph */
- /* and add it to `origin_x'> */
- /* */
- /* origin_x += slot->advance.x; */
- /* origin_x += slot->rsb_delta - slot->lsb_delta; */
- /* endfor */
- /* } */
- /* */
- /* Here is another small pseudo code fragment that shows how to use */
- /* `lsb_delta' and `rsb_delta' to improve integer positioning of */
- /* glyphs: */
- /* */
- /* { */
- /* FT_GlyphSlot slot = face->glyph; */
- /* FT_Pos origin_x = 0; */
- /* FT_Pos prev_rsb_delta = 0; */
- /* */
- /* */
- /* for all glyphs do */
- /* <compute kern between current and previous glyph */
- /* and add it to `origin_x'> */
- /* */
- /* <load glyph with `FT_Load_Glyph'> */
- /* */
- /* if ( prev_rsb_delta - slot->lsb_delta > 32 ) */
- /* origin_x -= 64; */
- /* else if ( prev_rsb_delta - slot->lsb_delta < -31 ) */
- /* origin_x += 64; */
- /* */
- /* prev_rsb_delta = slot->rsb_delta; */
- /* */
- /* <save glyph image, or render glyph, or ...> */
- /* */
- /* origin_x += slot->advance.x; */
- /* endfor */
- /* } */
- /* */
- /* If you use strong auto-hinting, you *must* apply these delta */
- /* values! Otherwise you will experience far too large inter-glyph */
- /* spacing at small rendering sizes in most cases. Note that it */
- /* doesn't harm to use the above code for other hinting modes also, */
- /* since the delta values are zero then. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_GlyphSlotRec
+ *
+ * @description:
+ * FreeType root glyph slot class structure. A glyph slot is a container
+ * where individual glyphs can be loaded, be they in outline or bitmap
+ * format.
+ *
+ * @fields:
+ * library ::
+ * A handle to the FreeType library instance this slot belongs to.
+ *
+ * face ::
+ * A handle to the parent face object.
+ *
+ * next ::
+ * In some cases (like some font tools), several glyph slots per face
+ * object can be a good thing. As this is rare, the glyph slots are
+ * listed through a direct, single-linked list using its `next` field.
+ *
+ * glyph_index ::
+ * [Since 2.10] The glyph index passed as an argument to @FT_Load_Glyph
+ * while initializing the glyph slot.
+ *
+ * generic ::
+ * A typeless pointer unused by the FreeType library or any of its
+ * drivers. It can be used by client applications to link their own
+ * data to each glyph slot object.
+ *
+ * metrics ::
+ * The metrics of the last loaded glyph in the slot. The returned
+ * values depend on the last load flags (see the @FT_Load_Glyph API
+ * function) and can be expressed either in 26.6 fractional pixels or
+ * font units.
+ *
+ * Note that even when the glyph image is transformed, the metrics are
+ * not.
+ *
+ * linearHoriAdvance ::
+ * The advance width of the unhinted glyph. Its value is expressed in
+ * 16.16 fractional pixels, unless @FT_LOAD_LINEAR_DESIGN is set when
+ * loading the glyph. This field can be important to perform correct
+ * WYSIWYG layout. Only relevant for outline glyphs.
+ *
+ * linearVertAdvance ::
+ * The advance height of the unhinted glyph. Its value is expressed in
+ * 16.16 fractional pixels, unless @FT_LOAD_LINEAR_DESIGN is set when
+ * loading the glyph. This field can be important to perform correct
+ * WYSIWYG layout. Only relevant for outline glyphs.
+ *
+ * advance ::
+ * This shorthand is, depending on @FT_LOAD_IGNORE_TRANSFORM, the
+ * transformed (hinted) advance width for the glyph, in 26.6 fractional
+ * pixel format. As specified with @FT_LOAD_VERTICAL_LAYOUT, it uses
+ * either the `horiAdvance` or the `vertAdvance` value of `metrics`
+ * field.
+ *
+ * format ::
+ * This field indicates the format of the image contained in the glyph
+ * slot. Typically @FT_GLYPH_FORMAT_BITMAP, @FT_GLYPH_FORMAT_OUTLINE,
+ * or @FT_GLYPH_FORMAT_COMPOSITE, but other values are possible.
+ *
+ * bitmap ::
+ * This field is used as a bitmap descriptor. Note that the address
+ * and content of the bitmap buffer can change between calls of
+ * @FT_Load_Glyph and a few other functions.
+ *
+ * bitmap_left ::
+ * The bitmap's left bearing expressed in integer pixels.
+ *
+ * bitmap_top ::
+ * The bitmap's top bearing expressed in integer pixels. This is the
+ * distance from the baseline to the top-most glyph scanline, upwards
+ * y~coordinates being **positive**.
+ *
+ * outline ::
+ * The outline descriptor for the current glyph image if its format is
+ * @FT_GLYPH_FORMAT_OUTLINE. Once a glyph is loaded, `outline` can be
+ * transformed, distorted, emboldened, etc. However, it must not be
+ * freed.
+ *
+ * [Since 2.10.1] If @FT_LOAD_NO_SCALE is set, outline coordinates of
+ * OpenType variation fonts for a selected instance are internally
+ * handled as 26.6 fractional font units but returned as (rounded)
+ * integers, as expected. To get unrounded font units, don't use
+ * @FT_LOAD_NO_SCALE but load the glyph with @FT_LOAD_NO_HINTING and
+ * scale it, using the font's `units_per_EM` value as the ppem.
+ *
+ * num_subglyphs ::
+ * The number of subglyphs in a composite glyph. This field is only
+ * valid for the composite glyph format that should normally only be
+ * loaded with the @FT_LOAD_NO_RECURSE flag.
+ *
+ * subglyphs ::
+ * An array of subglyph descriptors for composite glyphs. There are
+ * `num_subglyphs` elements in there. Currently internal to FreeType.
+ *
+ * control_data ::
+ * Certain font drivers can also return the control data for a given
+ * glyph image (e.g. TrueType bytecode, Type~1 charstrings, etc.).
+ * This field is a pointer to such data; it is currently internal to
+ * FreeType.
+ *
+ * control_len ::
+ * This is the length in bytes of the control data. Currently internal
+ * to FreeType.
+ *
+ * other ::
+ * Reserved.
+ *
+ * lsb_delta ::
+ * The difference between hinted and unhinted left side bearing while
+ * auto-hinting is active. Zero otherwise.
+ *
+ * rsb_delta ::
+ * The difference between hinted and unhinted right side bearing while
+ * auto-hinting is active. Zero otherwise.
+ *
+ * @note:
+ * If @FT_Load_Glyph is called with default flags (see @FT_LOAD_DEFAULT)
+ * the glyph image is loaded in the glyph slot in its native format
+ * (e.g., an outline glyph for TrueType and Type~1 formats). [Since 2.9]
+ * The prospective bitmap metrics are calculated according to
+ * @FT_LOAD_TARGET_XXX and other flags even for the outline glyph, even
+ * if @FT_LOAD_RENDER is not set.
+ *
+ * This image can later be converted into a bitmap by calling
+ * @FT_Render_Glyph. This function searches the current renderer for the
+ * native image's format, then invokes it.
+ *
+ * The renderer is in charge of transforming the native image through the
+ * slot's face transformation fields, then converting it into a bitmap
+ * that is returned in `slot->bitmap`.
+ *
+ * Note that `slot->bitmap_left` and `slot->bitmap_top` are also used to
+ * specify the position of the bitmap relative to the current pen
+ * position (e.g., coordinates (0,0) on the baseline). Of course,
+ * `slot->format` is also changed to @FT_GLYPH_FORMAT_BITMAP.
+ *
+ * Here is a small pseudo code fragment that shows how to use `lsb_delta`
+ * and `rsb_delta` to do fractional positioning of glyphs:
+ *
+ * ```
+ * FT_GlyphSlot slot = face->glyph;
+ * FT_Pos origin_x = 0;
+ *
+ *
+ * for all glyphs do
+ * <load glyph with `FT_Load_Glyph'>
+ *
+ * FT_Outline_Translate( slot->outline, origin_x & 63, 0 );
+ *
+ * <save glyph image, or render glyph, or ...>
+ *
+ * <compute kern between current and next glyph
+ * and add it to `origin_x'>
+ *
+ * origin_x += slot->advance.x;
+ * origin_x += slot->lsb_delta - slot->rsb_delta;
+ * endfor
+ * ```
+ *
+ * Here is another small pseudo code fragment that shows how to use
+ * `lsb_delta` and `rsb_delta` to improve integer positioning of glyphs:
+ *
+ * ```
+ * FT_GlyphSlot slot = face->glyph;
+ * FT_Pos origin_x = 0;
+ * FT_Pos prev_rsb_delta = 0;
+ *
+ *
+ * for all glyphs do
+ * <compute kern between current and previous glyph
+ * and add it to `origin_x'>
+ *
+ * <load glyph with `FT_Load_Glyph'>
+ *
+ * if ( prev_rsb_delta - slot->lsb_delta > 32 )
+ * origin_x -= 64;
+ * else if ( prev_rsb_delta - slot->lsb_delta < -31 )
+ * origin_x += 64;
+ *
+ * prev_rsb_delta = slot->rsb_delta;
+ *
+ * <save glyph image, or render glyph, or ...>
+ *
+ * origin_x += slot->advance.x;
+ * endfor
+ * ```
+ *
+ * If you use strong auto-hinting, you **must** apply these delta values!
+ * Otherwise you will experience far too large inter-glyph spacing at
+ * small rendering sizes in most cases. Note that it doesn't harm to use
+ * the above code for other hinting modes also, since the delta values
+ * are zero then.
+ */
typedef struct FT_GlyphSlotRec_
{
FT_Library library;
FT_Face face;
FT_GlyphSlot next;
- FT_UInt reserved; /* retained for binary compatibility */
+ FT_UInt glyph_index; /* new in 2.10; was reserved previously */
FT_Generic generic;
FT_Glyph_Metrics metrics;
@@ -1952,86 +1927,92 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Init_FreeType */
- /* */
- /* <Description> */
- /* Initialize a new FreeType library object. The set of modules */
- /* that are registered by this function is determined at build time. */
- /* */
- /* <Output> */
- /* alibrary :: A handle to a new library object. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* In case you want to provide your own memory allocating routines, */
- /* use @FT_New_Library instead, followed by a call to */
- /* @FT_Add_Default_Modules (or a series of calls to @FT_Add_Module) */
- /* and @FT_Set_Default_Properties. */
- /* */
- /* See the documentation of @FT_Library and @FT_Face for */
- /* multi-threading issues. */
- /* */
- /* If you need reference-counting (cf. @FT_Reference_Library), use */
- /* @FT_New_Library and @FT_Done_Library. */
- /* */
- /* If compilation option FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES is */
- /* set, this function reads the `FREETYPE_PROPERTIES' environment */
- /* variable to control driver properties. See section @properties */
- /* for more. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Init_FreeType
+ *
+ * @description:
+ * Initialize a new FreeType library object. The set of modules that are
+ * registered by this function is determined at build time.
+ *
+ * @output:
+ * alibrary ::
+ * A handle to a new library object.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * In case you want to provide your own memory allocating routines, use
+ * @FT_New_Library instead, followed by a call to @FT_Add_Default_Modules
+ * (or a series of calls to @FT_Add_Module) and
+ * @FT_Set_Default_Properties.
+ *
+ * See the documentation of @FT_Library and @FT_Face for multi-threading
+ * issues.
+ *
+ * If you need reference-counting (cf. @FT_Reference_Library), use
+ * @FT_New_Library and @FT_Done_Library.
+ *
+ * If compilation option `FT_CONFIG_OPTION_ENVIRONMENT_PROPERTIES` is
+ * set, this function reads the `FREETYPE_PROPERTIES` environment
+ * variable to control driver properties. See section @properties for
+ * more.
+ */
FT_EXPORT( FT_Error )
FT_Init_FreeType( FT_Library *alibrary );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Done_FreeType */
- /* */
- /* <Description> */
- /* Destroy a given FreeType library object and all of its children, */
- /* including resources, drivers, faces, sizes, etc. */
- /* */
- /* <Input> */
- /* library :: A handle to the target library object. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Done_FreeType
+ *
+ * @description:
+ * Destroy a given FreeType library object and all of its children,
+ * including resources, drivers, faces, sizes, etc.
+ *
+ * @input:
+ * library ::
+ * A handle to the target library object.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ */
FT_EXPORT( FT_Error )
FT_Done_FreeType( FT_Library library );
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* FT_OPEN_XXX */
- /* */
- /* <Description> */
- /* A list of bit field constants used within the `flags' field of the */
- /* @FT_Open_Args structure. */
- /* */
- /* <Values> */
- /* FT_OPEN_MEMORY :: This is a memory-based stream. */
- /* */
- /* FT_OPEN_STREAM :: Copy the stream from the `stream' field. */
- /* */
- /* FT_OPEN_PATHNAME :: Create a new input stream from a C~path */
- /* name. */
- /* */
- /* FT_OPEN_DRIVER :: Use the `driver' field. */
- /* */
- /* FT_OPEN_PARAMS :: Use the `num_params' and `params' fields. */
- /* */
- /* <Note> */
- /* The `FT_OPEN_MEMORY', `FT_OPEN_STREAM', and `FT_OPEN_PATHNAME' */
- /* flags are mutually exclusive. */
- /* */
+ /**************************************************************************
+ *
+ * @enum:
+ * FT_OPEN_XXX
+ *
+ * @description:
+ * A list of bit field constants used within the `flags` field of the
+ * @FT_Open_Args structure.
+ *
+ * @values:
+ * FT_OPEN_MEMORY ::
+ * This is a memory-based stream.
+ *
+ * FT_OPEN_STREAM ::
+ * Copy the stream from the `stream` field.
+ *
+ * FT_OPEN_PATHNAME ::
+ * Create a new input stream from a C~path name.
+ *
+ * FT_OPEN_DRIVER ::
+ * Use the `driver` field.
+ *
+ * FT_OPEN_PARAMS ::
+ * Use the `num_params` and `params` fields.
+ *
+ * @note:
+ * The `FT_OPEN_MEMORY`, `FT_OPEN_STREAM`, and `FT_OPEN_PATHNAME` flags
+ * are mutually exclusive.
+ */
#define FT_OPEN_MEMORY 0x1
#define FT_OPEN_STREAM 0x2
#define FT_OPEN_PATHNAME 0x4
@@ -2039,7 +2020,7 @@ FT_BEGIN_HEADER
#define FT_OPEN_PARAMS 0x10
- /* these constants are deprecated; use the corresponding `FT_OPEN_XXX' */
+ /* these constants are deprecated; use the corresponding `FT_OPEN_XXX` */
/* values instead */
#define ft_open_memory FT_OPEN_MEMORY
#define ft_open_stream FT_OPEN_STREAM
@@ -2048,24 +2029,26 @@ FT_BEGIN_HEADER
#define ft_open_params FT_OPEN_PARAMS
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_Parameter */
- /* */
- /* <Description> */
- /* A simple structure to pass more or less generic parameters to */
- /* @FT_Open_Face and @FT_Face_Properties. */
- /* */
- /* <Fields> */
- /* tag :: A four-byte identification tag. */
- /* */
- /* data :: A pointer to the parameter data. */
- /* */
- /* <Note> */
- /* The ID and function of parameters are driver-specific. See */
- /* section @parameter_tags for more information. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_Parameter
+ *
+ * @description:
+ * A simple structure to pass more or less generic parameters to
+ * @FT_Open_Face and @FT_Face_Properties.
+ *
+ * @fields:
+ * tag ::
+ * A four-byte identification tag.
+ *
+ * data ::
+ * A pointer to the parameter data.
+ *
+ * @note:
+ * The ID and function of parameters are driver-specific. See section
+ * @parameter_tags for more information.
+ */
typedef struct FT_Parameter_
{
FT_ULong tag;
@@ -2074,65 +2057,69 @@ FT_BEGIN_HEADER
} FT_Parameter;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_Open_Args */
- /* */
- /* <Description> */
- /* A structure to indicate how to open a new font file or stream. A */
- /* pointer to such a structure can be used as a parameter for the */
- /* functions @FT_Open_Face and @FT_Attach_Stream. */
- /* */
- /* <Fields> */
- /* flags :: A set of bit flags indicating how to use the */
- /* structure. */
- /* */
- /* memory_base :: The first byte of the file in memory. */
- /* */
- /* memory_size :: The size in bytes of the file in memory. */
- /* */
- /* pathname :: A pointer to an 8-bit file pathname. */
- /* */
- /* stream :: A handle to a source stream object. */
- /* */
- /* driver :: This field is exclusively used by @FT_Open_Face; */
- /* it simply specifies the font driver to use for */
- /* opening the face. If set to NULL, FreeType tries */
- /* to load the face with each one of the drivers in */
- /* its list. */
- /* */
- /* num_params :: The number of extra parameters. */
- /* */
- /* params :: Extra parameters passed to the font driver when */
- /* opening a new face. */
- /* */
- /* <Note> */
- /* The stream type is determined by the contents of `flags' that */
- /* are tested in the following order by @FT_Open_Face: */
- /* */
- /* If the @FT_OPEN_MEMORY bit is set, assume that this is a */
- /* memory file of `memory_size' bytes, located at `memory_address'. */
- /* The data are not copied, and the client is responsible for */
- /* releasing and destroying them _after_ the corresponding call to */
- /* @FT_Done_Face. */
- /* */
- /* Otherwise, if the @FT_OPEN_STREAM bit is set, assume that a */
- /* custom input stream `stream' is used. */
- /* */
- /* Otherwise, if the @FT_OPEN_PATHNAME bit is set, assume that this */
- /* is a normal file and use `pathname' to open it. */
- /* */
- /* If the @FT_OPEN_DRIVER bit is set, @FT_Open_Face only tries to */
- /* open the file with the driver whose handler is in `driver'. */
- /* */
- /* If the @FT_OPEN_PARAMS bit is set, the parameters given by */
- /* `num_params' and `params' is used. They are ignored otherwise. */
- /* */
- /* Ideally, both the `pathname' and `params' fields should be tagged */
- /* as `const'; this is missing for API backward compatibility. In */
- /* other words, applications should treat them as read-only. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_Open_Args
+ *
+ * @description:
+ * A structure to indicate how to open a new font file or stream. A
+ * pointer to such a structure can be used as a parameter for the
+ * functions @FT_Open_Face and @FT_Attach_Stream.
+ *
+ * @fields:
+ * flags ::
+ * A set of bit flags indicating how to use the structure.
+ *
+ * memory_base ::
+ * The first byte of the file in memory.
+ *
+ * memory_size ::
+ * The size in bytes of the file in memory.
+ *
+ * pathname ::
+ * A pointer to an 8-bit file pathname.
+ *
+ * stream ::
+ * A handle to a source stream object.
+ *
+ * driver ::
+ * This field is exclusively used by @FT_Open_Face; it simply specifies
+ * the font driver to use for opening the face. If set to `NULL`,
+ * FreeType tries to load the face with each one of the drivers in its
+ * list.
+ *
+ * num_params ::
+ * The number of extra parameters.
+ *
+ * params ::
+ * Extra parameters passed to the font driver when opening a new face.
+ *
+ * @note:
+ * The stream type is determined by the contents of `flags` that are
+ * tested in the following order by @FT_Open_Face:
+ *
+ * If the @FT_OPEN_MEMORY bit is set, assume that this is a memory file
+ * of `memory_size` bytes, located at `memory_address`. The data are not
+ * copied, and the client is responsible for releasing and destroying
+ * them _after_ the corresponding call to @FT_Done_Face.
+ *
+ * Otherwise, if the @FT_OPEN_STREAM bit is set, assume that a custom
+ * input stream `stream` is used.
+ *
+ * Otherwise, if the @FT_OPEN_PATHNAME bit is set, assume that this is a
+ * normal file and use `pathname` to open it.
+ *
+ * If the @FT_OPEN_DRIVER bit is set, @FT_Open_Face only tries to open
+ * the file with the driver whose handler is in `driver`.
+ *
+ * If the @FT_OPEN_PARAMS bit is set, the parameters given by
+ * `num_params` and `params` is used. They are ignored otherwise.
+ *
+ * Ideally, both the `pathname` and `params` fields should be tagged as
+ * 'const'; this is missing for API backward compatibility. In other
+ * words, applications should treat them as read-only.
+ */
typedef struct FT_Open_Args_
{
FT_UInt flags;
@@ -2147,34 +2134,37 @@ FT_BEGIN_HEADER
} FT_Open_Args;
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_New_Face */
- /* */
- /* <Description> */
- /* Call @FT_Open_Face to open a font by its pathname. */
- /* */
- /* <InOut> */
- /* library :: A handle to the library resource. */
- /* */
- /* <Input> */
- /* pathname :: A path to the font file. */
- /* */
- /* face_index :: See @FT_Open_Face for a detailed description of this */
- /* parameter. */
- /* */
- /* <Output> */
- /* aface :: A handle to a new face object. If `face_index' is */
- /* greater than or equal to zero, it must be non-NULL. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* Use @FT_Done_Face to destroy the created @FT_Face object (along */
- /* with its slot and sizes). */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_New_Face
+ *
+ * @description:
+ * Call @FT_Open_Face to open a font by its pathname.
+ *
+ * @inout:
+ * library ::
+ * A handle to the library resource.
+ *
+ * @input:
+ * pathname ::
+ * A path to the font file.
+ *
+ * face_index ::
+ * See @FT_Open_Face for a detailed description of this parameter.
+ *
+ * @output:
+ * aface ::
+ * A handle to a new face object. If `face_index` is greater than or
+ * equal to zero, it must be non-`NULL`.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * Use @FT_Done_Face to destroy the created @FT_Face object (along with
+ * its slot and sizes).
+ */
FT_EXPORT( FT_Error )
FT_New_Face( FT_Library library,
const char* filepathname,
@@ -2182,36 +2172,39 @@ FT_BEGIN_HEADER
FT_Face *aface );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_New_Memory_Face */
- /* */
- /* <Description> */
- /* Call @FT_Open_Face to open a font that has been loaded into */
- /* memory. */
- /* */
- /* <InOut> */
- /* library :: A handle to the library resource. */
- /* */
- /* <Input> */
- /* file_base :: A pointer to the beginning of the font data. */
- /* */
- /* file_size :: The size of the memory chunk used by the font data. */
- /* */
- /* face_index :: See @FT_Open_Face for a detailed description of this */
- /* parameter. */
- /* */
- /* <Output> */
- /* aface :: A handle to a new face object. If `face_index' is */
- /* greater than or equal to zero, it must be non-NULL. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* You must not deallocate the memory before calling @FT_Done_Face. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_New_Memory_Face
+ *
+ * @description:
+ * Call @FT_Open_Face to open a font that has been loaded into memory.
+ *
+ * @inout:
+ * library ::
+ * A handle to the library resource.
+ *
+ * @input:
+ * file_base ::
+ * A pointer to the beginning of the font data.
+ *
+ * file_size ::
+ * The size of the memory chunk used by the font data.
+ *
+ * face_index ::
+ * See @FT_Open_Face for a detailed description of this parameter.
+ *
+ * @output:
+ * aface ::
+ * A handle to a new face object. If `face_index` is greater than or
+ * equal to zero, it must be non-`NULL`.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * You must not deallocate the memory before calling @FT_Done_Face.
+ */
FT_EXPORT( FT_Error )
FT_New_Memory_Face( FT_Library library,
const FT_Byte* file_base,
@@ -2220,147 +2213,143 @@ FT_BEGIN_HEADER
FT_Face *aface );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Open_Face */
- /* */
- /* <Description> */
- /* Create a face object from a given resource described by */
- /* @FT_Open_Args. */
- /* */
- /* <InOut> */
- /* library :: A handle to the library resource. */
- /* */
- /* <Input> */
- /* args :: A pointer to an `FT_Open_Args' structure that must */
- /* be filled by the caller. */
- /* */
- /* face_index :: This field holds two different values. Bits 0-15 */
- /* are the index of the face in the font file (starting */
- /* with value~0). Set it to~0 if there is only one */
- /* face in the font file. */
- /* */
- /* [Since 2.6.1] Bits 16-30 are relevant to GX and */
- /* OpenType variation fonts only, specifying the named */
- /* instance index for the current face index (starting */
- /* with value~1; value~0 makes FreeType ignore named */
- /* instances). For non-variation fonts, bits 16-30 are */
- /* ignored. Assuming that you want to access the third */
- /* named instance in face~4, `face_index' should be set */
- /* to 0x00030004. If you want to access face~4 without */
- /* variation handling, simply set `face_index' to */
- /* value~4. */
- /* */
- /* `FT_Open_Face' and its siblings can be used to */
- /* quickly check whether the font format of a given */
- /* font resource is supported by FreeType. In general, */
- /* if the `face_index' argument is negative, the */
- /* function's return value is~0 if the font format is */
- /* recognized, or non-zero otherwise. The function */
- /* allocates a more or less empty face handle in */
- /* `*aface' (if `aface' isn't NULL); the only two */
- /* useful fields in this special case are */
- /* `face->num_faces' and `face->style_flags'. For any */
- /* negative value of `face_index', `face->num_faces' */
- /* gives the number of faces within the font file. For */
- /* the negative value `-(N+1)' (with `N' a non-negative */
- /* 16-bit value), bits 16-30 in `face->style_flags' */
- /* give the number of named instances in face `N' if we */
- /* have a variation font (or zero otherwise). After */
- /* examination, the returned @FT_Face structure should */
- /* be deallocated with a call to @FT_Done_Face. */
- /* */
- /* <Output> */
- /* aface :: A handle to a new face object. If `face_index' is */
- /* greater than or equal to zero, it must be non-NULL. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* Unlike FreeType 1.x, this function automatically creates a glyph */
- /* slot for the face object that can be accessed directly through */
- /* `face->glyph'. */
- /* */
- /* Each new face object created with this function also owns a */
- /* default @FT_Size object, accessible as `face->size'. */
- /* */
- /* One @FT_Library instance can have multiple face objects, this is, */
- /* @FT_Open_Face and its siblings can be called multiple times using */
- /* the same `library' argument. */
- /* */
- /* See the discussion of reference counters in the description of */
- /* @FT_Reference_Face. */
- /* */
- /* To loop over all faces, use code similar to the following snippet */
- /* (omitting the error handling). */
- /* */
- /* { */
- /* ... */
- /* FT_Face face; */
- /* FT_Long i, num_faces; */
- /* */
- /* */
- /* error = FT_Open_Face( library, args, -1, &face ); */
- /* if ( error ) { ... } */
- /* */
- /* num_faces = face->num_faces; */
- /* FT_Done_Face( face ); */
- /* */
- /* for ( i = 0; i < num_faces; i++ ) */
- /* { */
- /* ... */
- /* error = FT_Open_Face( library, args, i, &face ); */
- /* ... */
- /* FT_Done_Face( face ); */
- /* ... */
- /* } */
- /* } */
- /* */
- /* To loop over all valid values for `face_index', use something */
- /* similar to the following snippet, again without error handling. */
- /* The code accesses all faces immediately (thus only a single call */
- /* of `FT_Open_Face' within the do-loop), with and without named */
- /* instances. */
- /* */
- /* { */
- /* ... */
- /* FT_Face face; */
- /* */
- /* FT_Long num_faces = 0; */
- /* FT_Long num_instances = 0; */
- /* */
- /* FT_Long face_idx = 0; */
- /* FT_Long instance_idx = 0; */
- /* */
- /* */
- /* do */
- /* { */
- /* FT_Long id = ( instance_idx << 16 ) + face_idx; */
- /* */
- /* */
- /* error = FT_Open_Face( library, args, id, &face ); */
- /* if ( error ) { ... } */
- /* */
- /* num_faces = face->num_faces; */
- /* num_instances = face->style_flags >> 16; */
- /* */
- /* ... */
- /* */
- /* FT_Done_Face( face ); */
- /* */
- /* if ( instance_idx < num_instances ) */
- /* instance_idx++; */
- /* else */
- /* { */
- /* face_idx++; */
- /* instance_idx = 0; */
- /* } */
- /* */
- /* } while ( face_idx < num_faces ) */
- /* } */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Open_Face
+ *
+ * @description:
+ * Create a face object from a given resource described by @FT_Open_Args.
+ *
+ * @inout:
+ * library ::
+ * A handle to the library resource.
+ *
+ * @input:
+ * args ::
+ * A pointer to an `FT_Open_Args` structure that must be filled by the
+ * caller.
+ *
+ * face_index ::
+ * This field holds two different values. Bits 0-15 are the index of
+ * the face in the font file (starting with value~0). Set it to~0 if
+ * there is only one face in the font file.
+ *
+ * [Since 2.6.1] Bits 16-30 are relevant to GX and OpenType variation
+ * fonts only, specifying the named instance index for the current face
+ * index (starting with value~1; value~0 makes FreeType ignore named
+ * instances). For non-variation fonts, bits 16-30 are ignored.
+ * Assuming that you want to access the third named instance in face~4,
+ * `face_index` should be set to 0x00030004. If you want to access
+ * face~4 without variation handling, simply set `face_index` to
+ * value~4.
+ *
+ * `FT_Open_Face` and its siblings can be used to quickly check whether
+ * the font format of a given font resource is supported by FreeType.
+ * In general, if the `face_index` argument is negative, the function's
+ * return value is~0 if the font format is recognized, or non-zero
+ * otherwise. The function allocates a more or less empty face handle
+ * in `*aface` (if `aface` isn't `NULL`); the only two useful fields in
+ * this special case are `face->num_faces` and `face->style_flags`.
+ * For any negative value of `face_index`, `face->num_faces` gives the
+ * number of faces within the font file. For the negative value
+ * '-(N+1)' (with 'N' a non-negative 16-bit value), bits 16-30 in
+ * `face->style_flags` give the number of named instances in face 'N'
+ * if we have a variation font (or zero otherwise). After examination,
+ * the returned @FT_Face structure should be deallocated with a call to
+ * @FT_Done_Face.
+ *
+ * @output:
+ * aface ::
+ * A handle to a new face object. If `face_index` is greater than or
+ * equal to zero, it must be non-`NULL`.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * Unlike FreeType 1.x, this function automatically creates a glyph slot
+ * for the face object that can be accessed directly through
+ * `face->glyph`.
+ *
+ * Each new face object created with this function also owns a default
+ * @FT_Size object, accessible as `face->size`.
+ *
+ * One @FT_Library instance can have multiple face objects, this is,
+ * @FT_Open_Face and its siblings can be called multiple times using the
+ * same `library` argument.
+ *
+ * See the discussion of reference counters in the description of
+ * @FT_Reference_Face.
+ *
+ * @example:
+ * To loop over all faces, use code similar to the following snippet
+ * (omitting the error handling).
+ *
+ * ```
+ * ...
+ * FT_Face face;
+ * FT_Long i, num_faces;
+ *
+ *
+ * error = FT_Open_Face( library, args, -1, &face );
+ * if ( error ) { ... }
+ *
+ * num_faces = face->num_faces;
+ * FT_Done_Face( face );
+ *
+ * for ( i = 0; i < num_faces; i++ )
+ * {
+ * ...
+ * error = FT_Open_Face( library, args, i, &face );
+ * ...
+ * FT_Done_Face( face );
+ * ...
+ * }
+ * ```
+ *
+ * To loop over all valid values for `face_index`, use something similar
+ * to the following snippet, again without error handling. The code
+ * accesses all faces immediately (thus only a single call of
+ * `FT_Open_Face` within the do-loop), with and without named instances.
+ *
+ * ```
+ * ...
+ * FT_Face face;
+ *
+ * FT_Long num_faces = 0;
+ * FT_Long num_instances = 0;
+ *
+ * FT_Long face_idx = 0;
+ * FT_Long instance_idx = 0;
+ *
+ *
+ * do
+ * {
+ * FT_Long id = ( instance_idx << 16 ) + face_idx;
+ *
+ *
+ * error = FT_Open_Face( library, args, id, &face );
+ * if ( error ) { ... }
+ *
+ * num_faces = face->num_faces;
+ * num_instances = face->style_flags >> 16;
+ *
+ * ...
+ *
+ * FT_Done_Face( face );
+ *
+ * if ( instance_idx < num_instances )
+ * instance_idx++;
+ * else
+ * {
+ * face_idx++;
+ * instance_idx = 0;
+ * }
+ *
+ * } while ( face_idx < num_faces )
+ * ```
+ */
FT_EXPORT( FT_Error )
FT_Open_Face( FT_Library library,
const FT_Open_Args* args,
@@ -2368,204 +2357,208 @@ FT_BEGIN_HEADER
FT_Face *aface );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Attach_File */
- /* */
- /* <Description> */
- /* Call @FT_Attach_Stream to attach a file. */
- /* */
- /* <InOut> */
- /* face :: The target face object. */
- /* */
- /* <Input> */
- /* filepathname :: The pathname. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Attach_File
+ *
+ * @description:
+ * Call @FT_Attach_Stream to attach a file.
+ *
+ * @inout:
+ * face ::
+ * The target face object.
+ *
+ * @input:
+ * filepathname ::
+ * The pathname.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ */
FT_EXPORT( FT_Error )
FT_Attach_File( FT_Face face,
const char* filepathname );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Attach_Stream */
- /* */
- /* <Description> */
- /* `Attach' data to a face object. Normally, this is used to read */
- /* additional information for the face object. For example, you can */
- /* attach an AFM file that comes with a Type~1 font to get the */
- /* kerning values and other metrics. */
- /* */
- /* <InOut> */
- /* face :: The target face object. */
- /* */
- /* <Input> */
- /* parameters :: A pointer to @FT_Open_Args that must be filled by */
- /* the caller. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* The meaning of the `attach' (i.e., what really happens when the */
- /* new file is read) is not fixed by FreeType itself. It really */
- /* depends on the font format (and thus the font driver). */
- /* */
- /* Client applications are expected to know what they are doing */
- /* when invoking this function. Most drivers simply do not implement */
- /* file or stream attachments. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Attach_Stream
+ *
+ * @description:
+ * 'Attach' data to a face object. Normally, this is used to read
+ * additional information for the face object. For example, you can
+ * attach an AFM file that comes with a Type~1 font to get the kerning
+ * values and other metrics.
+ *
+ * @inout:
+ * face ::
+ * The target face object.
+ *
+ * @input:
+ * parameters ::
+ * A pointer to @FT_Open_Args that must be filled by the caller.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * The meaning of the 'attach' (i.e., what really happens when the new
+ * file is read) is not fixed by FreeType itself. It really depends on
+ * the font format (and thus the font driver).
+ *
+ * Client applications are expected to know what they are doing when
+ * invoking this function. Most drivers simply do not implement file or
+ * stream attachments.
+ */
FT_EXPORT( FT_Error )
FT_Attach_Stream( FT_Face face,
FT_Open_Args* parameters );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Reference_Face */
- /* */
- /* <Description> */
- /* A counter gets initialized to~1 at the time an @FT_Face structure */
- /* is created. This function increments the counter. @FT_Done_Face */
- /* then only destroys a face if the counter is~1, otherwise it simply */
- /* decrements the counter. */
- /* */
- /* This function helps in managing life-cycles of structures that */
- /* reference @FT_Face objects. */
- /* */
- /* <Input> */
- /* face :: A handle to a target face object. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Since> */
- /* 2.4.2 */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Reference_Face
+ *
+ * @description:
+ * A counter gets initialized to~1 at the time an @FT_Face structure is
+ * created. This function increments the counter. @FT_Done_Face then
+ * only destroys a face if the counter is~1, otherwise it simply
+ * decrements the counter.
+ *
+ * This function helps in managing life-cycles of structures that
+ * reference @FT_Face objects.
+ *
+ * @input:
+ * face ::
+ * A handle to a target face object.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @since:
+ * 2.4.2
+ */
FT_EXPORT( FT_Error )
FT_Reference_Face( FT_Face face );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Done_Face */
- /* */
- /* <Description> */
- /* Discard a given face object, as well as all of its child slots and */
- /* sizes. */
- /* */
- /* <Input> */
- /* face :: A handle to a target face object. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* See the discussion of reference counters in the description of */
- /* @FT_Reference_Face. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Done_Face
+ *
+ * @description:
+ * Discard a given face object, as well as all of its child slots and
+ * sizes.
+ *
+ * @input:
+ * face ::
+ * A handle to a target face object.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * See the discussion of reference counters in the description of
+ * @FT_Reference_Face.
+ */
FT_EXPORT( FT_Error )
FT_Done_Face( FT_Face face );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Select_Size */
- /* */
- /* <Description> */
- /* Select a bitmap strike. To be more precise, this function sets */
- /* the scaling factors of the active @FT_Size object in a face so */
- /* that bitmaps from this particular strike are taken by */
- /* @FT_Load_Glyph and friends. */
- /* */
- /* <InOut> */
- /* face :: A handle to a target face object. */
- /* */
- /* <Input> */
- /* strike_index :: The index of the bitmap strike in the */
- /* `available_sizes' field of @FT_FaceRec structure. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* For bitmaps embedded in outline fonts it is common that only a */
- /* subset of the available glyphs at a given ppem value is available. */
- /* FreeType silently uses outlines if there is no bitmap for a given */
- /* glyph index. */
- /* */
- /* For GX and OpenType variation fonts, a bitmap strike makes sense */
- /* only if the default instance is active (this is, no glyph */
- /* variation takes place); otherwise, FreeType simply ignores bitmap */
- /* strikes. The same is true for all named instances that are */
- /* different from the default instance. */
- /* */
- /* Don't use this function if you are using the FreeType cache API. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Select_Size
+ *
+ * @description:
+ * Select a bitmap strike. To be more precise, this function sets the
+ * scaling factors of the active @FT_Size object in a face so that
+ * bitmaps from this particular strike are taken by @FT_Load_Glyph and
+ * friends.
+ *
+ * @inout:
+ * face ::
+ * A handle to a target face object.
+ *
+ * @input:
+ * strike_index ::
+ * The index of the bitmap strike in the `available_sizes` field of
+ * @FT_FaceRec structure.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * For bitmaps embedded in outline fonts it is common that only a subset
+ * of the available glyphs at a given ppem value is available. FreeType
+ * silently uses outlines if there is no bitmap for a given glyph index.
+ *
+ * For GX and OpenType variation fonts, a bitmap strike makes sense only
+ * if the default instance is active (this is, no glyph variation takes
+ * place); otherwise, FreeType simply ignores bitmap strikes. The same
+ * is true for all named instances that are different from the default
+ * instance.
+ *
+ * Don't use this function if you are using the FreeType cache API.
+ */
FT_EXPORT( FT_Error )
FT_Select_Size( FT_Face face,
FT_Int strike_index );
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* FT_Size_Request_Type */
- /* */
- /* <Description> */
- /* An enumeration type that lists the supported size request types, */
- /* i.e., what input size (in font units) maps to the requested output */
- /* size (in pixels, as computed from the arguments of */
- /* @FT_Size_Request). */
- /* */
- /* <Values> */
- /* FT_SIZE_REQUEST_TYPE_NOMINAL :: */
- /* The nominal size. The `units_per_EM' field of @FT_FaceRec is */
- /* used to determine both scaling values. */
- /* */
- /* This is the standard scaling found in most applications. In */
- /* particular, use this size request type for TrueType fonts if */
- /* they provide optical scaling or something similar. Note, */
- /* however, that `units_per_EM' is a rather abstract value which */
- /* bears no relation to the actual size of the glyphs in a font. */
- /* */
- /* FT_SIZE_REQUEST_TYPE_REAL_DIM :: */
- /* The real dimension. The sum of the `ascender' and (minus of) */
- /* the `descender' fields of @FT_FaceRec is used to determine both */
- /* scaling values. */
- /* */
- /* FT_SIZE_REQUEST_TYPE_BBOX :: */
- /* The font bounding box. The width and height of the `bbox' field */
- /* of @FT_FaceRec are used to determine the horizontal and vertical */
- /* scaling value, respectively. */
- /* */
- /* FT_SIZE_REQUEST_TYPE_CELL :: */
- /* The `max_advance_width' field of @FT_FaceRec is used to */
- /* determine the horizontal scaling value; the vertical scaling */
- /* value is determined the same way as */
- /* @FT_SIZE_REQUEST_TYPE_REAL_DIM does. Finally, both scaling */
- /* values are set to the smaller one. This type is useful if you */
- /* want to specify the font size for, say, a window of a given */
- /* dimension and 80x24 cells. */
- /* */
- /* FT_SIZE_REQUEST_TYPE_SCALES :: */
- /* Specify the scaling values directly. */
- /* */
- /* <Note> */
- /* The above descriptions only apply to scalable formats. For bitmap */
- /* formats, the behaviour is up to the driver. */
- /* */
- /* See the note section of @FT_Size_Metrics if you wonder how size */
- /* requesting relates to scaling values. */
- /* */
+ /**************************************************************************
+ *
+ * @enum:
+ * FT_Size_Request_Type
+ *
+ * @description:
+ * An enumeration type that lists the supported size request types, i.e.,
+ * what input size (in font units) maps to the requested output size (in
+ * pixels, as computed from the arguments of @FT_Size_Request).
+ *
+ * @values:
+ * FT_SIZE_REQUEST_TYPE_NOMINAL ::
+ * The nominal size. The `units_per_EM` field of @FT_FaceRec is used
+ * to determine both scaling values.
+ *
+ * This is the standard scaling found in most applications. In
+ * particular, use this size request type for TrueType fonts if they
+ * provide optical scaling or something similar. Note, however, that
+ * `units_per_EM` is a rather abstract value which bears no relation to
+ * the actual size of the glyphs in a font.
+ *
+ * FT_SIZE_REQUEST_TYPE_REAL_DIM ::
+ * The real dimension. The sum of the `ascender` and (minus of) the
+ * `descender` fields of @FT_FaceRec is used to determine both scaling
+ * values.
+ *
+ * FT_SIZE_REQUEST_TYPE_BBOX ::
+ * The font bounding box. The width and height of the `bbox` field of
+ * @FT_FaceRec are used to determine the horizontal and vertical
+ * scaling value, respectively.
+ *
+ * FT_SIZE_REQUEST_TYPE_CELL ::
+ * The `max_advance_width` field of @FT_FaceRec is used to determine
+ * the horizontal scaling value; the vertical scaling value is
+ * determined the same way as @FT_SIZE_REQUEST_TYPE_REAL_DIM does.
+ * Finally, both scaling values are set to the smaller one. This type
+ * is useful if you want to specify the font size for, say, a window of
+ * a given dimension and 80x24 cells.
+ *
+ * FT_SIZE_REQUEST_TYPE_SCALES ::
+ * Specify the scaling values directly.
+ *
+ * @note:
+ * The above descriptions only apply to scalable formats. For bitmap
+ * formats, the behaviour is up to the driver.
+ *
+ * See the note section of @FT_Size_Metrics if you wonder how size
+ * requesting relates to scaling values.
+ */
typedef enum FT_Size_Request_Type_
{
FT_SIZE_REQUEST_TYPE_NOMINAL,
@@ -2579,42 +2572,45 @@ FT_BEGIN_HEADER
} FT_Size_Request_Type;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_Size_RequestRec */
- /* */
- /* <Description> */
- /* A structure to model a size request. */
- /* */
- /* <Fields> */
- /* type :: See @FT_Size_Request_Type. */
- /* */
- /* width :: The desired width, given as a 26.6 fractional */
- /* point value (with 72pt = 1in). */
- /* */
- /* height :: The desired height, given as a 26.6 fractional */
- /* point value (with 72pt = 1in). */
- /* */
- /* horiResolution :: The horizontal resolution (dpi, i.e., pixels per */
- /* inch). If set to zero, `width' is treated as a */
- /* 26.6 fractional *pixel* value, which gets */
- /* internally rounded to an integer. */
- /* */
- /* vertResolution :: The vertical resolution (dpi, i.e., pixels per */
- /* inch). If set to zero, `height' is treated as a */
- /* 26.6 fractional *pixel* value, which gets */
- /* internally rounded to an integer. */
- /* */
- /* <Note> */
- /* If `width' is zero, the horizontal scaling value is set equal */
- /* to the vertical scaling value, and vice versa. */
- /* */
- /* If `type' is FT_SIZE_REQUEST_TYPE_SCALES, `width' and `height' are */
- /* interpreted directly as 16.16 fractional scaling values, without */
- /* any further modification, and both `horiResolution' and */
- /* `vertResolution' are ignored. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_Size_RequestRec
+ *
+ * @description:
+ * A structure to model a size request.
+ *
+ * @fields:
+ * type ::
+ * See @FT_Size_Request_Type.
+ *
+ * width ::
+ * The desired width, given as a 26.6 fractional point value (with 72pt
+ * = 1in).
+ *
+ * height ::
+ * The desired height, given as a 26.6 fractional point value (with
+ * 72pt = 1in).
+ *
+ * horiResolution ::
+ * The horizontal resolution (dpi, i.e., pixels per inch). If set to
+ * zero, `width` is treated as a 26.6 fractional **pixel** value, which
+ * gets internally rounded to an integer.
+ *
+ * vertResolution ::
+ * The vertical resolution (dpi, i.e., pixels per inch). If set to
+ * zero, `height` is treated as a 26.6 fractional **pixel** value,
+ * which gets internally rounded to an integer.
+ *
+ * @note:
+ * If `width` is zero, the horizontal scaling value is set equal to the
+ * vertical scaling value, and vice versa.
+ *
+ * If `type` is `FT_SIZE_REQUEST_TYPE_SCALES`, `width` and `height` are
+ * interpreted directly as 16.16 fractional scaling values, without any
+ * further modification, and both `horiResolution` and `vertResolution`
+ * are ignored.
+ */
typedef struct FT_Size_RequestRec_
{
FT_Size_Request_Type type;
@@ -2626,96 +2622,102 @@ FT_BEGIN_HEADER
} FT_Size_RequestRec;
- /*************************************************************************/
- /* */
- /* <Struct> */
- /* FT_Size_Request */
- /* */
- /* <Description> */
- /* A handle to a size request structure. */
- /* */
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_Size_Request
+ *
+ * @description:
+ * A handle to a size request structure.
+ */
typedef struct FT_Size_RequestRec_ *FT_Size_Request;
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Request_Size */
- /* */
- /* <Description> */
- /* Resize the scale of the active @FT_Size object in a face. */
- /* */
- /* <InOut> */
- /* face :: A handle to a target face object. */
- /* */
- /* <Input> */
- /* req :: A pointer to a @FT_Size_RequestRec. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* Although drivers may select the bitmap strike matching the */
- /* request, you should not rely on this if you intend to select a */
- /* particular bitmap strike. Use @FT_Select_Size instead in that */
- /* case. */
- /* */
- /* The relation between the requested size and the resulting glyph */
- /* size is dependent entirely on how the size is defined in the */
- /* source face. The font designer chooses the final size of each */
- /* glyph relative to this size. For more information refer to */
- /* `https://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html'. */
- /* */
- /* Contrary to @FT_Set_Char_Size, this function doesn't have special */
- /* code to normalize zero-valued widths, heights, or resolutions */
- /* (which lead to errors in most cases). */
- /* */
- /* Don't use this function if you are using the FreeType cache API. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Request_Size
+ *
+ * @description:
+ * Resize the scale of the active @FT_Size object in a face.
+ *
+ * @inout:
+ * face ::
+ * A handle to a target face object.
+ *
+ * @input:
+ * req ::
+ * A pointer to a @FT_Size_RequestRec.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * Although drivers may select the bitmap strike matching the request,
+ * you should not rely on this if you intend to select a particular
+ * bitmap strike. Use @FT_Select_Size instead in that case.
+ *
+ * The relation between the requested size and the resulting glyph size
+ * is dependent entirely on how the size is defined in the source face.
+ * The font designer chooses the final size of each glyph relative to
+ * this size. For more information refer to
+ * 'https://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html'.
+ *
+ * Contrary to @FT_Set_Char_Size, this function doesn't have special code
+ * to normalize zero-valued widths, heights, or resolutions (which lead
+ * to errors in most cases).
+ *
+ * Don't use this function if you are using the FreeType cache API.
+ */
FT_EXPORT( FT_Error )
FT_Request_Size( FT_Face face,
FT_Size_Request req );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Set_Char_Size */
- /* */
- /* <Description> */
- /* Call @FT_Request_Size to request the nominal size (in points). */
- /* */
- /* <InOut> */
- /* face :: A handle to a target face object. */
- /* */
- /* <Input> */
- /* char_width :: The nominal width, in 26.6 fractional points. */
- /* */
- /* char_height :: The nominal height, in 26.6 fractional points. */
- /* */
- /* horz_resolution :: The horizontal resolution in dpi. */
- /* */
- /* vert_resolution :: The vertical resolution in dpi. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* While this function allows fractional points as input values, the */
- /* resulting ppem value for the given resolution is always rounded to */
- /* the nearest integer. */
- /* */
- /* If either the character width or height is zero, it is set equal */
- /* to the other value. */
- /* */
- /* If either the horizontal or vertical resolution is zero, it is set */
- /* equal to the other value. */
- /* */
- /* A character width or height smaller than 1pt is set to 1pt; if */
- /* both resolution values are zero, they are set to 72dpi. */
- /* */
- /* Don't use this function if you are using the FreeType cache API. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Set_Char_Size
+ *
+ * @description:
+ * Call @FT_Request_Size to request the nominal size (in points).
+ *
+ * @inout:
+ * face ::
+ * A handle to a target face object.
+ *
+ * @input:
+ * char_width ::
+ * The nominal width, in 26.6 fractional points.
+ *
+ * char_height ::
+ * The nominal height, in 26.6 fractional points.
+ *
+ * horz_resolution ::
+ * The horizontal resolution in dpi.
+ *
+ * vert_resolution ::
+ * The vertical resolution in dpi.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * While this function allows fractional points as input values, the
+ * resulting ppem value for the given resolution is always rounded to the
+ * nearest integer.
+ *
+ * If either the character width or height is zero, it is set equal to
+ * the other value.
+ *
+ * If either the horizontal or vertical resolution is zero, it is set
+ * equal to the other value.
+ *
+ * A character width or height smaller than 1pt is set to 1pt; if both
+ * resolution values are zero, they are set to 72dpi.
+ *
+ * Don't use this function if you are using the FreeType cache API.
+ */
FT_EXPORT( FT_Error )
FT_Set_Char_Size( FT_Face face,
FT_F26Dot6 char_width,
@@ -2724,134 +2726,138 @@ FT_BEGIN_HEADER
FT_UInt vert_resolution );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Set_Pixel_Sizes */
- /* */
- /* <Description> */
- /* Call @FT_Request_Size to request the nominal size (in pixels). */
- /* */
- /* <InOut> */
- /* face :: A handle to the target face object. */
- /* */
- /* <Input> */
- /* pixel_width :: The nominal width, in pixels. */
- /* */
- /* pixel_height :: The nominal height, in pixels. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* You should not rely on the resulting glyphs matching or being */
- /* constrained to this pixel size. Refer to @FT_Request_Size to */
- /* understand how requested sizes relate to actual sizes. */
- /* */
- /* Don't use this function if you are using the FreeType cache API. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Set_Pixel_Sizes
+ *
+ * @description:
+ * Call @FT_Request_Size to request the nominal size (in pixels).
+ *
+ * @inout:
+ * face ::
+ * A handle to the target face object.
+ *
+ * @input:
+ * pixel_width ::
+ * The nominal width, in pixels.
+ *
+ * pixel_height ::
+ * The nominal height, in pixels.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * You should not rely on the resulting glyphs matching or being
+ * constrained to this pixel size. Refer to @FT_Request_Size to
+ * understand how requested sizes relate to actual sizes.
+ *
+ * Don't use this function if you are using the FreeType cache API.
+ */
FT_EXPORT( FT_Error )
FT_Set_Pixel_Sizes( FT_Face face,
FT_UInt pixel_width,
FT_UInt pixel_height );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Load_Glyph */
- /* */
- /* <Description> */
- /* Load a glyph into the glyph slot of a face object. */
- /* */
- /* <InOut> */
- /* face :: A handle to the target face object where the glyph */
- /* is loaded. */
- /* */
- /* <Input> */
- /* glyph_index :: The index of the glyph in the font file. For */
- /* CID-keyed fonts (either in PS or in CFF format) */
- /* this argument specifies the CID value. */
- /* */
- /* load_flags :: A flag indicating what to load for this glyph. The */
- /* @FT_LOAD_XXX constants can be used to control the */
- /* glyph loading process (e.g., whether the outline */
- /* should be scaled, whether to load bitmaps or not, */
- /* whether to hint the outline, etc). */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* The loaded glyph may be transformed. See @FT_Set_Transform for */
- /* the details. */
- /* */
- /* For subsetted CID-keyed fonts, `FT_Err_Invalid_Argument' is */
- /* returned for invalid CID values (this is, for CID values that */
- /* don't have a corresponding glyph in the font). See the discussion */
- /* of the @FT_FACE_FLAG_CID_KEYED flag for more details. */
- /* */
- /* If you receive `FT_Err_Glyph_Too_Big', try getting the glyph */
- /* outline at EM size, then scale it manually and fill it as a */
- /* graphics operation. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Load_Glyph
+ *
+ * @description:
+ * Load a glyph into the glyph slot of a face object.
+ *
+ * @inout:
+ * face ::
+ * A handle to the target face object where the glyph is loaded.
+ *
+ * @input:
+ * glyph_index ::
+ * The index of the glyph in the font file. For CID-keyed fonts
+ * (either in PS or in CFF format) this argument specifies the CID
+ * value.
+ *
+ * load_flags ::
+ * A flag indicating what to load for this glyph. The @FT_LOAD_XXX
+ * constants can be used to control the glyph loading process (e.g.,
+ * whether the outline should be scaled, whether to load bitmaps or
+ * not, whether to hint the outline, etc).
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * The loaded glyph may be transformed. See @FT_Set_Transform for the
+ * details.
+ *
+ * For subsetted CID-keyed fonts, `FT_Err_Invalid_Argument` is returned
+ * for invalid CID values (this is, for CID values that don't have a
+ * corresponding glyph in the font). See the discussion of the
+ * @FT_FACE_FLAG_CID_KEYED flag for more details.
+ *
+ * If you receive `FT_Err_Glyph_Too_Big`, try getting the glyph outline
+ * at EM size, then scale it manually and fill it as a graphics
+ * operation.
+ */
FT_EXPORT( FT_Error )
FT_Load_Glyph( FT_Face face,
FT_UInt glyph_index,
FT_Int32 load_flags );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Load_Char */
- /* */
- /* <Description> */
- /* Load a glyph into the glyph slot of a face object, accessed by its */
- /* character code. */
- /* */
- /* <InOut> */
- /* face :: A handle to a target face object where the glyph */
- /* is loaded. */
- /* */
- /* <Input> */
- /* char_code :: The glyph's character code, according to the */
- /* current charmap used in the face. */
- /* */
- /* load_flags :: A flag indicating what to load for this glyph. The */
- /* @FT_LOAD_XXX constants can be used to control the */
- /* glyph loading process (e.g., whether the outline */
- /* should be scaled, whether to load bitmaps or not, */
- /* whether to hint the outline, etc). */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* This function simply calls @FT_Get_Char_Index and @FT_Load_Glyph. */
- /* */
- /* Many fonts contain glyphs that can't be loaded by this function */
- /* since its glyph indices are not listed in any of the font's */
- /* charmaps. */
- /* */
- /* If no active cmap is set up (i.e., `face->charmap' is zero), the */
- /* call to @FT_Get_Char_Index is omitted, and the function behaves */
- /* identically to @FT_Load_Glyph. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Load_Char
+ *
+ * @description:
+ * Load a glyph into the glyph slot of a face object, accessed by its
+ * character code.
+ *
+ * @inout:
+ * face ::
+ * A handle to a target face object where the glyph is loaded.
+ *
+ * @input:
+ * char_code ::
+ * The glyph's character code, according to the current charmap used in
+ * the face.
+ *
+ * load_flags ::
+ * A flag indicating what to load for this glyph. The @FT_LOAD_XXX
+ * constants can be used to control the glyph loading process (e.g.,
+ * whether the outline should be scaled, whether to load bitmaps or
+ * not, whether to hint the outline, etc).
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * This function simply calls @FT_Get_Char_Index and @FT_Load_Glyph.
+ *
+ * Many fonts contain glyphs that can't be loaded by this function since
+ * its glyph indices are not listed in any of the font's charmaps.
+ *
+ * If no active cmap is set up (i.e., `face->charmap` is zero), the call
+ * to @FT_Get_Char_Index is omitted, and the function behaves identically
+ * to @FT_Load_Glyph.
+ */
FT_EXPORT( FT_Error )
FT_Load_Char( FT_Face face,
FT_ULong char_code,
FT_Int32 load_flags );
- /*************************************************************************
+ /**************************************************************************
*
* @enum:
* FT_LOAD_XXX
*
* @description:
- * A list of bit field constants for @FT_Load_Glyph to indicate what
- * kind of operations to perform during glyph loading.
+ * A list of bit field constants for @FT_Load_Glyph to indicate what kind
+ * of operations to perform during glyph loading.
*
* @values:
* FT_LOAD_DEFAULT ::
@@ -2859,15 +2865,14 @@ FT_BEGIN_HEADER
* operation. In this case, the following happens:
*
* 1. FreeType looks for a bitmap for the glyph corresponding to the
- * face's current size. If one is found, the function returns.
- * The bitmap data can be accessed from the glyph slot (see note
- * below).
+ * face's current size. If one is found, the function returns. The
+ * bitmap data can be accessed from the glyph slot (see note below).
*
* 2. If no embedded bitmap is searched for or found, FreeType looks
- * for a scalable outline. If one is found, it is loaded from
- * the font file, scaled to device pixels, then `hinted' to the
- * pixel grid in order to optimize it. The outline data can be
- * accessed from the glyph slot (see note below).
+ * for a scalable outline. If one is found, it is loaded from the font
+ * file, scaled to device pixels, then 'hinted' to the pixel grid in
+ * order to optimize it. The outline data can be accessed from the
+ * glyph slot (see note below).
*
* Note that by default the glyph loader doesn't render outlines into
* bitmaps. The following flags are used to modify this default
@@ -2879,14 +2884,14 @@ FT_BEGIN_HEADER
* This flag implies @FT_LOAD_NO_HINTING and @FT_LOAD_NO_BITMAP, and
* unsets @FT_LOAD_RENDER.
*
- * If the font is `tricky' (see @FT_FACE_FLAG_TRICKY for more), using
- * FT_LOAD_NO_SCALE usually yields meaningless outlines because the
- * subglyphs must be scaled and positioned with hinting instructions.
- * This can be solved by loading the font without FT_LOAD_NO_SCALE and
- * setting the character size to `font->units_per_EM'.
+ * If the font is 'tricky' (see @FT_FACE_FLAG_TRICKY for more), using
+ * `FT_LOAD_NO_SCALE` usually yields meaningless outlines because the
+ * subglyphs must be scaled and positioned with hinting instructions.
+ * This can be solved by loading the font without `FT_LOAD_NO_SCALE`
+ * and setting the character size to `font->units_per_EM`.
*
* FT_LOAD_NO_HINTING ::
- * Disable hinting. This generally generates `blurrier' bitmap glyphs
+ * Disable hinting. This generally generates 'blurrier' bitmap glyphs
* when the glyph are rendered in any of the anti-aliased modes. See
* also the note below.
*
@@ -2907,34 +2912,37 @@ FT_BEGIN_HEADER
*
* FT_LOAD_VERTICAL_LAYOUT ::
* Load the glyph for vertical text layout. In particular, the
- * `advance' value in the @FT_GlyphSlotRec structure is set to the
- * `vertAdvance' value of the `metrics' field.
+ * `advance` value in the @FT_GlyphSlotRec structure is set to the
+ * `vertAdvance` value of the `metrics` field.
*
- * In case @FT_HAS_VERTICAL doesn't return true, you shouldn't use
- * this flag currently. Reason is that in this case vertical metrics
- * get synthesized, and those values are not always consistent across
+ * In case @FT_HAS_VERTICAL doesn't return true, you shouldn't use this
+ * flag currently. Reason is that in this case vertical metrics get
+ * synthesized, and those values are not always consistent across
* various font formats.
*
* FT_LOAD_FORCE_AUTOHINT ::
- * Prefer the auto-hinter over the font's native hinter. See also
- * the note below.
+ * Prefer the auto-hinter over the font's native hinter. See also the
+ * note below.
*
* FT_LOAD_PEDANTIC ::
* Make the font driver perform pedantic verifications during glyph
- * loading. This is mostly used to detect broken glyphs in fonts.
- * By default, FreeType tries to handle broken fonts also.
+ * loading and hinting. This is mostly used to detect broken glyphs in
+ * fonts. By default, FreeType tries to handle broken fonts also.
*
* In particular, errors from the TrueType bytecode engine are not
- * passed to the application if this flag is not set; this might
- * result in partially hinted or distorted glyphs in case a glyph's
- * bytecode is buggy.
+ * passed to the application if this flag is not set; this might result
+ * in partially hinted or distorted glyphs in case a glyph's bytecode
+ * is buggy.
*
* FT_LOAD_NO_RECURSE ::
- * Don't load composite glyphs recursively. Instead, the font
- * driver should set the `num_subglyph' and `subglyphs' values of
- * the glyph slot accordingly, and set `glyph->format' to
- * @FT_GLYPH_FORMAT_COMPOSITE. The description of subglyphs can
- * then be accessed with @FT_Get_SubGlyph_Info.
+ * Don't load composite glyphs recursively. Instead, the font driver
+ * fills the `num_subglyph` and `subglyphs` values of the glyph slot;
+ * it also sets `glyph->format` to @FT_GLYPH_FORMAT_COMPOSITE. The
+ * description of subglyphs can then be accessed with
+ * @FT_Get_SubGlyph_Info.
+ *
+ * Don't use this flag for retrieving metrics information since some
+ * font drivers only return rudimentary data.
*
* This flag implies @FT_LOAD_NO_SCALE and @FT_LOAD_IGNORE_TRANSFORM.
*
@@ -2951,23 +2959,35 @@ FT_BEGIN_HEADER
* monochrome-optimized hinting algorithm is used.
*
* FT_LOAD_LINEAR_DESIGN ::
- * Keep `linearHoriAdvance' and `linearVertAdvance' fields of
- * @FT_GlyphSlotRec in font units. See @FT_GlyphSlotRec for
- * details.
+ * Keep `linearHoriAdvance` and `linearVertAdvance` fields of
+ * @FT_GlyphSlotRec in font units. See @FT_GlyphSlotRec for details.
*
* FT_LOAD_NO_AUTOHINT ::
* Disable the auto-hinter. See also the note below.
*
* FT_LOAD_COLOR ::
+ * Load colored glyphs. There are slight differences depending on the
+ * font format.
+ *
* [Since 2.5] Load embedded color bitmap images. The resulting color
- * bitmaps, if available, will have the @FT_PIXEL_MODE_BGRA format.
- * If the flag is not set and color bitmaps are found, they are
- * converted to 256-level gray bitmaps transparently, using the
- * @FT_PIXEL_MODE_GRAY format.
+ * bitmaps, if available, will have the @FT_PIXEL_MODE_BGRA format,
+ * with pre-multiplied color channels. If the flag is not set and
+ * color bitmaps are found, they are converted to 256-level gray
+ * bitmaps, using the @FT_PIXEL_MODE_GRAY format.
+ *
+ * [Since 2.10, experimental] If the glyph index contains an entry in
+ * the face's 'COLR' table with a 'CPAL' palette table (as defined in
+ * the OpenType specification), make @FT_Render_Glyph provide a default
+ * blending of the color glyph layers associated with the glyph index,
+ * using the same bitmap format as embedded color bitmap images. This
+ * is mainly for convenience; for full control of color layers use
+ * @FT_Get_Color_Glyph_Layer and FreeType's color functions like
+ * @FT_Palette_Select instead of setting @FT_LOAD_COLOR for rendering
+ * so that the client application can handle blending by itself.
*
* FT_LOAD_COMPUTE_METRICS ::
- * [Since 2.6.1] Compute glyph metrics from the glyph data, without
- * the use of bundled metrics tables (for example, the `hdmx' table in
+ * [Since 2.6.1] Compute glyph metrics from the glyph data, without the
+ * use of bundled metrics tables (for example, the 'hdmx' table in
* TrueType fonts). This flag is mainly used by font validating or
* font editing applications, which need to ignore, verify, or edit
* those tables.
@@ -2976,9 +2996,9 @@ FT_BEGIN_HEADER
*
* FT_LOAD_BITMAP_METRICS_ONLY ::
* [Since 2.7.1] Request loading of the metrics and bitmap image
- * information of a (possibly embedded) bitmap glyph without
- * allocating or copying the bitmap image data itself. No effect if
- * the target glyph is not a bitmap image.
+ * information of a (possibly embedded) bitmap glyph without allocating
+ * or copying the bitmap image data itself. No effect if the target
+ * glyph is not a bitmap image.
*
* This flag unsets @FT_LOAD_RENDER.
*
@@ -2993,8 +3013,8 @@ FT_BEGIN_HEADER
* @FT_FACE_FLAG_HINTER) is preferred over the auto-hinter. You can
* disable hinting by setting @FT_LOAD_NO_HINTING or change the
* precedence by setting @FT_LOAD_FORCE_AUTOHINT. You can also set
- * @FT_LOAD_NO_AUTOHINT in case you don't want the auto-hinter to be
- * used at all.
+ * @FT_LOAD_NO_AUTOHINT in case you don't want the auto-hinter to be used
+ * at all.
*
* See the description of @FT_FACE_FLAG_TRICKY for a special exception
* (affecting only a handful of Asian fonts).
@@ -3005,7 +3025,7 @@ FT_BEGIN_HEADER
* Note that the auto-hinter needs a valid Unicode cmap (either a native
* one or synthesized by FreeType) for producing correct results. If a
* font provides an incorrect mapping (for example, assigning the
- * character code U+005A, LATIN CAPITAL LETTER Z, to a glyph depicting a
+ * character code U+005A, LATIN CAPITAL LETTER~Z, to a glyph depicting a
* mathematical integral sign), the auto-hinter might produce useless
* results.
*
@@ -3025,7 +3045,7 @@ FT_BEGIN_HEADER
#define FT_LOAD_MONOCHROME ( 1L << 12 )
#define FT_LOAD_LINEAR_DESIGN ( 1L << 13 )
#define FT_LOAD_NO_AUTOHINT ( 1L << 15 )
- /* Bits 16-19 are used by `FT_LOAD_TARGET_' */
+ /* Bits 16-19 are used by `FT_LOAD_TARGET_` */
#define FT_LOAD_COLOR ( 1L << 20 )
#define FT_LOAD_COMPUTE_METRICS ( 1L << 21 )
#define FT_LOAD_BITMAP_METRICS_ONLY ( 1L << 22 )
@@ -3044,19 +3064,17 @@ FT_BEGIN_HEADER
*
* @description:
* A list of values to select a specific hinting algorithm for the
- * hinter. You should OR one of these values to your `load_flags'
- * when calling @FT_Load_Glyph.
+ * hinter. You should OR one of these values to your `load_flags` when
+ * calling @FT_Load_Glyph.
*
- * Note that a font's native hinters may ignore the hinting algorithm
- * you have specified (e.g., the TrueType bytecode interpreter). You
- * can set @FT_LOAD_FORCE_AUTOHINT to ensure that the auto-hinter is
- * used.
+ * Note that a font's native hinters may ignore the hinting algorithm you
+ * have specified (e.g., the TrueType bytecode interpreter). You can set
+ * @FT_LOAD_FORCE_AUTOHINT to ensure that the auto-hinter is used.
*
* @values:
* FT_LOAD_TARGET_NORMAL ::
* The default hinting algorithm, optimized for standard gray-level
- * rendering. For monochrome output, use @FT_LOAD_TARGET_MONO
- * instead.
+ * rendering. For monochrome output, use @FT_LOAD_TARGET_MONO instead.
*
* FT_LOAD_TARGET_LIGHT ::
* A lighter hinting algorithm for gray-level modes. Many generated
@@ -3069,13 +3087,13 @@ FT_BEGIN_HEADER
* auto-hinter.
*
* Advance widths are rounded to integer values; however, using the
- * `lsb_delta' and `rsb_delta' fields of @FT_GlyphSlotRec, it is
+ * `lsb_delta` and `rsb_delta` fields of @FT_GlyphSlotRec, it is
* possible to get fractional advance widths for subpixel positioning
* (which is recommended to use).
*
- * If configuration option AF_CONFIG_OPTION_TT_SIZE_METRICS is active,
- * TrueType-like metrics are used to make this mode behave similarly
- * as in unpatched FreeType versions between 2.4.6 and 2.7.1
+ * If configuration option `AF_CONFIG_OPTION_TT_SIZE_METRICS` is
+ * active, TrueType-like metrics are used to make this mode behave
+ * similarly as in unpatched FreeType versions between 2.4.6 and 2.7.1
* (inclusive).
*
* FT_LOAD_TARGET_MONO ::
@@ -3083,6 +3101,12 @@ FT_BEGIN_HEADER
* output. The result is probably unpleasant if the glyph is rendered
* in non-monochrome modes.
*
+ * Note that for outline fonts only the TrueType font driver has proper
+ * monochrome hinting support, provided the TTFs contain hints for B/W
+ * rendering (which most fonts no longer provide). If these conditions
+ * are not met it is very likely that you get ugly results at smaller
+ * sizes.
+ *
* FT_LOAD_TARGET_LCD ::
* A variant of @FT_LOAD_TARGET_LIGHT optimized for horizontally
* decimated LCD displays.
@@ -3092,25 +3116,25 @@ FT_BEGIN_HEADER
* decimated LCD displays.
*
* @note:
- * You should use only _one_ of the FT_LOAD_TARGET_XXX values in your
- * `load_flags'. They can't be ORed.
+ * You should use only _one_ of the `FT_LOAD_TARGET_XXX` values in your
+ * `load_flags`. They can't be ORed.
*
* If @FT_LOAD_RENDER is also set, the glyph is rendered in the
* corresponding mode (i.e., the mode that matches the used algorithm
- * best). An exception is FT_LOAD_TARGET_MONO since it implies
+ * best). An exception is `FT_LOAD_TARGET_MONO` since it implies
* @FT_LOAD_MONOCHROME.
*
* You can use a hinting algorithm that doesn't correspond to the same
- * rendering mode. As an example, it is possible to use the `light'
+ * rendering mode. As an example, it is possible to use the 'light'
* hinting algorithm and have the results rendered in horizontal LCD
* pixel mode, with code like
*
- * {
- * FT_Load_Glyph( face, glyph_index,
- * load_flags | FT_LOAD_TARGET_LIGHT );
+ * ```
+ * FT_Load_Glyph( face, glyph_index,
+ * load_flags | FT_LOAD_TARGET_LIGHT );
*
- * FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD );
- * }
+ * FT_Render_Glyph( face->glyph, FT_RENDER_MODE_LCD );
+ * ```
*
* In general, you should stick with one rendering mode. For example,
* switching between @FT_LOAD_TARGET_NORMAL and @FT_LOAD_TARGET_MONO
@@ -3142,98 +3166,98 @@ FT_BEGIN_HEADER
#define FT_LOAD_TARGET_MODE( x ) ( (FT_Render_Mode)( ( (x) >> 16 ) & 15 ) )
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Set_Transform */
- /* */
- /* <Description> */
- /* Set the transformation that is applied to glyph images when they */
- /* are loaded into a glyph slot through @FT_Load_Glyph. */
- /* */
- /* <InOut> */
- /* face :: A handle to the source face object. */
- /* */
- /* <Input> */
- /* matrix :: A pointer to the transformation's 2x2 matrix. Use NULL */
- /* for the identity matrix. */
- /* delta :: A pointer to the translation vector. Use NULL for the */
- /* null vector. */
- /* */
- /* <Note> */
- /* The transformation is only applied to scalable image formats after */
- /* the glyph has been loaded. It means that hinting is unaltered by */
- /* the transformation and is performed on the character size given in */
- /* the last call to @FT_Set_Char_Size or @FT_Set_Pixel_Sizes. */
- /* */
- /* Note that this also transforms the `face.glyph.advance' field, but */
- /* *not* the values in `face.glyph.metrics'. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Set_Transform
+ *
+ * @description:
+ * Set the transformation that is applied to glyph images when they are
+ * loaded into a glyph slot through @FT_Load_Glyph.
+ *
+ * @inout:
+ * face ::
+ * A handle to the source face object.
+ *
+ * @input:
+ * matrix ::
+ * A pointer to the transformation's 2x2 matrix. Use `NULL` for the
+ * identity matrix.
+ * delta ::
+ * A pointer to the translation vector. Use `NULL` for the null vector.
+ *
+ * @note:
+ * The transformation is only applied to scalable image formats after the
+ * glyph has been loaded. It means that hinting is unaltered by the
+ * transformation and is performed on the character size given in the
+ * last call to @FT_Set_Char_Size or @FT_Set_Pixel_Sizes.
+ *
+ * Note that this also transforms the `face.glyph.advance` field, but
+ * **not** the values in `face.glyph.metrics`.
+ */
FT_EXPORT( void )
FT_Set_Transform( FT_Face face,
FT_Matrix* matrix,
FT_Vector* delta );
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* FT_Render_Mode */
- /* */
- /* <Description> */
- /* Render modes supported by FreeType~2. Each mode corresponds to a */
- /* specific type of scanline conversion performed on the outline. */
- /* */
- /* For bitmap fonts and embedded bitmaps the `bitmap->pixel_mode' */
- /* field in the @FT_GlyphSlotRec structure gives the format of the */
- /* returned bitmap. */
- /* */
- /* All modes except @FT_RENDER_MODE_MONO use 256 levels of opacity, */
- /* indicating pixel coverage. Use linear alpha blending and gamma */
- /* correction to correctly render non-monochrome glyph bitmaps onto a */
- /* surface; see @FT_Render_Glyph. */
- /* */
- /* <Values> */
- /* FT_RENDER_MODE_NORMAL :: */
- /* Default render mode; it corresponds to 8-bit anti-aliased */
- /* bitmaps. */
- /* */
- /* FT_RENDER_MODE_LIGHT :: */
- /* This is equivalent to @FT_RENDER_MODE_NORMAL. It is only */
- /* defined as a separate value because render modes are also used */
- /* indirectly to define hinting algorithm selectors. See */
- /* @FT_LOAD_TARGET_XXX for details. */
- /* */
- /* FT_RENDER_MODE_MONO :: */
- /* This mode corresponds to 1-bit bitmaps (with 2~levels of */
- /* opacity). */
- /* */
- /* FT_RENDER_MODE_LCD :: */
- /* This mode corresponds to horizontal RGB and BGR subpixel */
- /* displays like LCD screens. It produces 8-bit bitmaps that are */
- /* 3~times the width of the original glyph outline in pixels, and */
- /* which use the @FT_PIXEL_MODE_LCD mode. */
- /* */
- /* FT_RENDER_MODE_LCD_V :: */
- /* This mode corresponds to vertical RGB and BGR subpixel displays */
- /* (like PDA screens, rotated LCD displays, etc.). It produces */
- /* 8-bit bitmaps that are 3~times the height of the original */
- /* glyph outline in pixels and use the @FT_PIXEL_MODE_LCD_V mode. */
- /* */
- /* <Note> */
- /* Should you define FT_CONFIG_OPTION_SUBPIXEL_RENDERING in your */
- /* `ftoption.h', which enables patented ClearType-style rendering, */
- /* the LCD-optimized glyph bitmaps should be filtered to reduce color */
- /* fringes inherent to this technology. You can either set up LCD */
- /* filtering with @FT_Library_SetLcdFilter or @FT_Face_Properties, */
- /* or do the filtering yourself. The default FreeType LCD rendering */
- /* technology does not require filtering. */
- /* */
- /* The selected render mode only affects vector glyphs of a font. */
- /* Embedded bitmaps often have a different pixel mode like */
- /* @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform */
- /* them into 8-bit pixmaps. */
- /* */
+ /**************************************************************************
+ *
+ * @enum:
+ * FT_Render_Mode
+ *
+ * @description:
+ * Render modes supported by FreeType~2. Each mode corresponds to a
+ * specific type of scanline conversion performed on the outline.
+ *
+ * For bitmap fonts and embedded bitmaps the `bitmap->pixel_mode` field
+ * in the @FT_GlyphSlotRec structure gives the format of the returned
+ * bitmap.
+ *
+ * All modes except @FT_RENDER_MODE_MONO use 256 levels of opacity,
+ * indicating pixel coverage. Use linear alpha blending and gamma
+ * correction to correctly render non-monochrome glyph bitmaps onto a
+ * surface; see @FT_Render_Glyph.
+ *
+ * @values:
+ * FT_RENDER_MODE_NORMAL ::
+ * Default render mode; it corresponds to 8-bit anti-aliased bitmaps.
+ *
+ * FT_RENDER_MODE_LIGHT ::
+ * This is equivalent to @FT_RENDER_MODE_NORMAL. It is only defined as
+ * a separate value because render modes are also used indirectly to
+ * define hinting algorithm selectors. See @FT_LOAD_TARGET_XXX for
+ * details.
+ *
+ * FT_RENDER_MODE_MONO ::
+ * This mode corresponds to 1-bit bitmaps (with 2~levels of opacity).
+ *
+ * FT_RENDER_MODE_LCD ::
+ * This mode corresponds to horizontal RGB and BGR subpixel displays
+ * like LCD screens. It produces 8-bit bitmaps that are 3~times the
+ * width of the original glyph outline in pixels, and which use the
+ * @FT_PIXEL_MODE_LCD mode.
+ *
+ * FT_RENDER_MODE_LCD_V ::
+ * This mode corresponds to vertical RGB and BGR subpixel displays
+ * (like PDA screens, rotated LCD displays, etc.). It produces 8-bit
+ * bitmaps that are 3~times the height of the original glyph outline in
+ * pixels and use the @FT_PIXEL_MODE_LCD_V mode.
+ *
+ * @note:
+ * Should you define `FT_CONFIG_OPTION_SUBPIXEL_RENDERING` in your
+ * `ftoption.h`, which enables patented ClearType-style rendering, the
+ * LCD-optimized glyph bitmaps should be filtered to reduce color fringes
+ * inherent to this technology. You can either set up LCD filtering with
+ * @FT_Library_SetLcdFilter or @FT_Face_Properties, or do the filtering
+ * yourself. The default FreeType LCD rendering technology does not
+ * require filtering.
+ *
+ * The selected render mode only affects vector glyphs of a font.
+ * Embedded bitmaps often have a different pixel mode like
+ * @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform them
+ * into 8-bit pixmaps.
+ */
typedef enum FT_Render_Mode_
{
FT_RENDER_MODE_NORMAL = 0,
@@ -3248,147 +3272,149 @@ FT_BEGIN_HEADER
/* these constants are deprecated; use the corresponding */
- /* `FT_Render_Mode' values instead */
+ /* `FT_Render_Mode` values instead */
#define ft_render_mode_normal FT_RENDER_MODE_NORMAL
#define ft_render_mode_mono FT_RENDER_MODE_MONO
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Render_Glyph */
- /* */
- /* <Description> */
- /* Convert a given glyph image to a bitmap. It does so by inspecting */
- /* the glyph image format, finding the relevant renderer, and */
- /* invoking it. */
- /* */
- /* <InOut> */
- /* slot :: A handle to the glyph slot containing the image to */
- /* convert. */
- /* */
- /* <Input> */
- /* render_mode :: The render mode used to render the glyph image into */
- /* a bitmap. See @FT_Render_Mode for a list of */
- /* possible values. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* To get meaningful results, font scaling values must be set with */
- /* functions like @FT_Set_Char_Size before calling `FT_Render_Glyph'. */
- /* */
- /* When FreeType outputs a bitmap of a glyph, it really outputs an */
- /* alpha coverage map. If a pixel is completely covered by a */
- /* filled-in outline, the bitmap contains 0xFF at that pixel, meaning */
- /* that 0xFF/0xFF fraction of that pixel is covered, meaning the */
- /* pixel is 100% black (or 0% bright). If a pixel is only 50% */
- /* covered (value 0x80), the pixel is made 50% black (50% bright or a */
- /* middle shade of grey). 0% covered means 0% black (100% bright or */
- /* white). */
- /* */
- /* On high-DPI screens like on smartphones and tablets, the pixels */
- /* are so small that their chance of being completely covered and */
- /* therefore completely black are fairly good. On the low-DPI */
- /* screens, however, the situation is different. The pixels are too */
- /* large for most of the details of a glyph and shades of gray are */
- /* the norm rather than the exception. */
- /* */
- /* This is relevant because all our screens have a second problem: */
- /* they are not linear. 1~+~1 is not~2. Twice the value does not */
- /* result in twice the brightness. When a pixel is only 50% covered, */
- /* the coverage map says 50% black, and this translates to a pixel */
- /* value of 128 when you use 8~bits per channel (0-255). However, */
- /* this does not translate to 50% brightness for that pixel on our */
- /* sRGB and gamma~2.2 screens. Due to their non-linearity, they */
- /* dwell longer in the darks and only a pixel value of about 186 */
- /* results in 50% brightness -- 128 ends up too dark on both bright */
- /* and dark backgrounds. The net result is that dark text looks */
- /* burnt-out, pixely and blotchy on bright background, bright text */
- /* too frail on dark backgrounds, and colored text on colored */
- /* background (for example, red on green) seems to have dark halos or */
- /* `dirt' around it. The situation is especially ugly for diagonal */
- /* stems like in `w' glyph shapes where the quality of FreeType's */
- /* anti-aliasing depends on the correct display of grays. On */
- /* high-DPI screens where smaller, fully black pixels reign supreme, */
- /* this doesn't matter, but on our low-DPI screens with all the gray */
- /* shades, it does. 0% and 100% brightness are the same things in */
- /* linear and non-linear space, just all the shades in-between */
- /* aren't. */
- /* */
- /* The blending function for placing text over a background is */
- /* */
- /* { */
- /* dst = alpha * src + (1 - alpha) * dst , */
- /* } */
- /* */
- /* which is known as the OVER operator. */
- /* */
- /* To correctly composite an antialiased pixel of a glyph onto a */
- /* surface, */
- /* */
- /* 1. take the foreground and background colors (e.g., in sRGB space) */
- /* and apply gamma to get them in a linear space, */
- /* */
- /* 2. use OVER to blend the two linear colors using the glyph pixel */
- /* as the alpha value (remember, the glyph bitmap is an alpha */
- /* coverage bitmap), and */
- /* */
- /* 3. apply inverse gamma to the blended pixel and write it back to */
- /* the image. */
- /* */
- /* Internal testing at Adobe found that a target inverse gamma of~1.8 */
- /* for step~3 gives good results across a wide range of displays with */
- /* an sRGB gamma curve or a similar one. */
- /* */
- /* This process can cost performance. There is an approximation that */
- /* does not need to know about the background color; see */
- /* https://bel.fi/alankila/lcd/ and */
- /* https://bel.fi/alankila/lcd/alpcor.html for details. */
- /* */
- /* *ATTENTION*: Linear blending is even more important when dealing */
- /* with subpixel-rendered glyphs to prevent color-fringing! A */
- /* subpixel-rendered glyph must first be filtered with a filter that */
- /* gives equal weight to the three color primaries and does not */
- /* exceed a sum of 0x100, see section @lcd_filtering. Then the */
- /* only difference to gray linear blending is that subpixel-rendered */
- /* linear blending is done 3~times per pixel: red foreground subpixel */
- /* to red background subpixel and so on for green and blue. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Render_Glyph
+ *
+ * @description:
+ * Convert a given glyph image to a bitmap. It does so by inspecting the
+ * glyph image format, finding the relevant renderer, and invoking it.
+ *
+ * @inout:
+ * slot ::
+ * A handle to the glyph slot containing the image to convert.
+ *
+ * @input:
+ * render_mode ::
+ * The render mode used to render the glyph image into a bitmap. See
+ * @FT_Render_Mode for a list of possible values.
+ *
+ * If @FT_RENDER_MODE_NORMAL is used, a previous call of @FT_Load_Glyph
+ * with flag @FT_LOAD_COLOR makes FT_Render_Glyph provide a default
+ * blending of colored glyph layers associated with the current glyph
+ * slot (provided the font contains such layers) instead of rendering
+ * the glyph slot's outline. This is an experimental feature; see
+ * @FT_LOAD_COLOR for more information.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * To get meaningful results, font scaling values must be set with
+ * functions like @FT_Set_Char_Size before calling `FT_Render_Glyph`.
+ *
+ * When FreeType outputs a bitmap of a glyph, it really outputs an alpha
+ * coverage map. If a pixel is completely covered by a filled-in
+ * outline, the bitmap contains 0xFF at that pixel, meaning that
+ * 0xFF/0xFF fraction of that pixel is covered, meaning the pixel is 100%
+ * black (or 0% bright). If a pixel is only 50% covered (value 0x80),
+ * the pixel is made 50% black (50% bright or a middle shade of grey).
+ * 0% covered means 0% black (100% bright or white).
+ *
+ * On high-DPI screens like on smartphones and tablets, the pixels are so
+ * small that their chance of being completely covered and therefore
+ * completely black are fairly good. On the low-DPI screens, however,
+ * the situation is different. The pixels are too large for most of the
+ * details of a glyph and shades of gray are the norm rather than the
+ * exception.
+ *
+ * This is relevant because all our screens have a second problem: they
+ * are not linear. 1~+~1 is not~2. Twice the value does not result in
+ * twice the brightness. When a pixel is only 50% covered, the coverage
+ * map says 50% black, and this translates to a pixel value of 128 when
+ * you use 8~bits per channel (0-255). However, this does not translate
+ * to 50% brightness for that pixel on our sRGB and gamma~2.2 screens.
+ * Due to their non-linearity, they dwell longer in the darks and only a
+ * pixel value of about 186 results in 50% brightness -- 128 ends up too
+ * dark on both bright and dark backgrounds. The net result is that dark
+ * text looks burnt-out, pixely and blotchy on bright background, bright
+ * text too frail on dark backgrounds, and colored text on colored
+ * background (for example, red on green) seems to have dark halos or
+ * 'dirt' around it. The situation is especially ugly for diagonal stems
+ * like in 'w' glyph shapes where the quality of FreeType's anti-aliasing
+ * depends on the correct display of grays. On high-DPI screens where
+ * smaller, fully black pixels reign supreme, this doesn't matter, but on
+ * our low-DPI screens with all the gray shades, it does. 0% and 100%
+ * brightness are the same things in linear and non-linear space, just
+ * all the shades in-between aren't.
+ *
+ * The blending function for placing text over a background is
+ *
+ * ```
+ * dst = alpha * src + (1 - alpha) * dst ,
+ * ```
+ *
+ * which is known as the OVER operator.
+ *
+ * To correctly composite an antialiased pixel of a glyph onto a surface,
+ *
+ * 1. take the foreground and background colors (e.g., in sRGB space)
+ * and apply gamma to get them in a linear space,
+ *
+ * 2. use OVER to blend the two linear colors using the glyph pixel
+ * as the alpha value (remember, the glyph bitmap is an alpha coverage
+ * bitmap), and
+ *
+ * 3. apply inverse gamma to the blended pixel and write it back to
+ * the image.
+ *
+ * Internal testing at Adobe found that a target inverse gamma of~1.8 for
+ * step~3 gives good results across a wide range of displays with an sRGB
+ * gamma curve or a similar one.
+ *
+ * This process can cost performance. There is an approximation that
+ * does not need to know about the background color; see
+ * https://bel.fi/alankila/lcd/ and
+ * https://bel.fi/alankila/lcd/alpcor.html for details.
+ *
+ * **ATTENTION**: Linear blending is even more important when dealing
+ * with subpixel-rendered glyphs to prevent color-fringing! A
+ * subpixel-rendered glyph must first be filtered with a filter that
+ * gives equal weight to the three color primaries and does not exceed a
+ * sum of 0x100, see section @lcd_rendering. Then the only difference to
+ * gray linear blending is that subpixel-rendered linear blending is done
+ * 3~times per pixel: red foreground subpixel to red background subpixel
+ * and so on for green and blue.
+ */
FT_EXPORT( FT_Error )
FT_Render_Glyph( FT_GlyphSlot slot,
FT_Render_Mode render_mode );
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* FT_Kerning_Mode */
- /* */
- /* <Description> */
- /* An enumeration to specify the format of kerning values returned by */
- /* @FT_Get_Kerning. */
- /* */
- /* <Values> */
- /* FT_KERNING_DEFAULT :: Return grid-fitted kerning distances in */
- /* 26.6 fractional pixels. */
- /* */
- /* FT_KERNING_UNFITTED :: Return un-grid-fitted kerning distances in */
- /* 26.6 fractional pixels. */
- /* */
- /* FT_KERNING_UNSCALED :: Return the kerning vector in original font */
- /* units. */
- /* */
- /* <Note> */
- /* FT_KERNING_DEFAULT returns full pixel values; it also makes */
- /* FreeType heuristically scale down kerning distances at small ppem */
- /* values so that they don't become too big. */
- /* */
- /* Both FT_KERNING_DEFAULT and FT_KERNING_UNFITTED use the current */
- /* horizontal scaling factor (as set e.g. with @FT_Set_Char_Size) to */
- /* convert font units to pixels. */
- /* */
+ /**************************************************************************
+ *
+ * @enum:
+ * FT_Kerning_Mode
+ *
+ * @description:
+ * An enumeration to specify the format of kerning values returned by
+ * @FT_Get_Kerning.
+ *
+ * @values:
+ * FT_KERNING_DEFAULT ::
+ * Return grid-fitted kerning distances in 26.6 fractional pixels.
+ *
+ * FT_KERNING_UNFITTED ::
+ * Return un-grid-fitted kerning distances in 26.6 fractional pixels.
+ *
+ * FT_KERNING_UNSCALED ::
+ * Return the kerning vector in original font units.
+ *
+ * @note:
+ * `FT_KERNING_DEFAULT` returns full pixel values; it also makes FreeType
+ * heuristically scale down kerning distances at small ppem values so
+ * that they don't become too big.
+ *
+ * Both `FT_KERNING_DEFAULT` and `FT_KERNING_UNFITTED` use the current
+ * horizontal scaling factor (as set e.g. with @FT_Set_Char_Size) to
+ * convert font units to pixels.
+ */
typedef enum FT_Kerning_Mode_
{
FT_KERNING_DEFAULT = 0,
@@ -3399,50 +3425,53 @@ FT_BEGIN_HEADER
/* these constants are deprecated; use the corresponding */
- /* `FT_Kerning_Mode' values instead */
+ /* `FT_Kerning_Mode` values instead */
#define ft_kerning_default FT_KERNING_DEFAULT
#define ft_kerning_unfitted FT_KERNING_UNFITTED
#define ft_kerning_unscaled FT_KERNING_UNSCALED
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_Kerning */
- /* */
- /* <Description> */
- /* Return the kerning vector between two glyphs of the same face. */
- /* */
- /* <Input> */
- /* face :: A handle to a source face object. */
- /* */
- /* left_glyph :: The index of the left glyph in the kern pair. */
- /* */
- /* right_glyph :: The index of the right glyph in the kern pair. */
- /* */
- /* kern_mode :: See @FT_Kerning_Mode for more information. */
- /* Determines the scale and dimension of the returned */
- /* kerning vector. */
- /* */
- /* <Output> */
- /* akerning :: The kerning vector. This is either in font units, */
- /* fractional pixels (26.6 format), or pixels for */
- /* scalable formats, and in pixels for fixed-sizes */
- /* formats. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* Only horizontal layouts (left-to-right & right-to-left) are */
- /* supported by this method. Other layouts, or more sophisticated */
- /* kernings, are out of the scope of this API function -- they can be */
- /* implemented through format-specific interfaces. */
- /* */
- /* Kerning for OpenType fonts implemented in a `GPOS' table is not */
- /* supported; use @FT_HAS_KERNING to find out whether a font has data */
- /* that can be extracted with `FT_Get_Kerning'. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_Kerning
+ *
+ * @description:
+ * Return the kerning vector between two glyphs of the same face.
+ *
+ * @input:
+ * face ::
+ * A handle to a source face object.
+ *
+ * left_glyph ::
+ * The index of the left glyph in the kern pair.
+ *
+ * right_glyph ::
+ * The index of the right glyph in the kern pair.
+ *
+ * kern_mode ::
+ * See @FT_Kerning_Mode for more information. Determines the scale and
+ * dimension of the returned kerning vector.
+ *
+ * @output:
+ * akerning ::
+ * The kerning vector. This is either in font units, fractional pixels
+ * (26.6 format), or pixels for scalable formats, and in pixels for
+ * fixed-sizes formats.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * Only horizontal layouts (left-to-right & right-to-left) are supported
+ * by this method. Other layouts, or more sophisticated kernings, are
+ * out of the scope of this API function -- they can be implemented
+ * through format-specific interfaces.
+ *
+ * Kerning for OpenType fonts implemented in a 'GPOS' table is not
+ * supported; use @FT_HAS_KERNING to find out whether a font has data
+ * that can be extracted with `FT_Get_Kerning`.
+ */
FT_EXPORT( FT_Error )
FT_Get_Kerning( FT_Face face,
FT_UInt left_glyph,
@@ -3451,39 +3480,42 @@ FT_BEGIN_HEADER
FT_Vector *akerning );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_Track_Kerning */
- /* */
- /* <Description> */
- /* Return the track kerning for a given face object at a given size. */
- /* */
- /* <Input> */
- /* face :: A handle to a source face object. */
- /* */
- /* point_size :: The point size in 16.16 fractional points. */
- /* */
- /* degree :: The degree of tightness. Increasingly negative */
- /* values represent tighter track kerning, while */
- /* increasingly positive values represent looser track */
- /* kerning. Value zero means no track kerning. */
- /* */
- /* <Output> */
- /* akerning :: The kerning in 16.16 fractional points, to be */
- /* uniformly applied between all glyphs. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* Currently, only the Type~1 font driver supports track kerning, */
- /* using data from AFM files (if attached with @FT_Attach_File or */
- /* @FT_Attach_Stream). */
- /* */
- /* Only very few AFM files come with track kerning data; please refer */
- /* to Adobe's AFM specification for more details. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_Track_Kerning
+ *
+ * @description:
+ * Return the track kerning for a given face object at a given size.
+ *
+ * @input:
+ * face ::
+ * A handle to a source face object.
+ *
+ * point_size ::
+ * The point size in 16.16 fractional points.
+ *
+ * degree ::
+ * The degree of tightness. Increasingly negative values represent
+ * tighter track kerning, while increasingly positive values represent
+ * looser track kerning. Value zero means no track kerning.
+ *
+ * @output:
+ * akerning ::
+ * The kerning in 16.16 fractional points, to be uniformly applied
+ * between all glyphs.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * Currently, only the Type~1 font driver supports track kerning, using
+ * data from AFM files (if attached with @FT_Attach_File or
+ * @FT_Attach_Stream).
+ *
+ * Only very few AFM files come with track kerning data; please refer to
+ * Adobe's AFM specification for more details.
+ */
FT_EXPORT( FT_Error )
FT_Get_Track_Kerning( FT_Face face,
FT_Fixed point_size,
@@ -3491,45 +3523,46 @@ FT_BEGIN_HEADER
FT_Fixed* akerning );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_Glyph_Name */
- /* */
- /* <Description> */
- /* Retrieve the ASCII name of a given glyph in a face. This only */
- /* works for those faces where @FT_HAS_GLYPH_NAMES(face) returns~1. */
- /* */
- /* <Input> */
- /* face :: A handle to a source face object. */
- /* */
- /* glyph_index :: The glyph index. */
- /* */
- /* buffer_max :: The maximum number of bytes available in the */
- /* buffer. */
- /* */
- /* <Output> */
- /* buffer :: A pointer to a target buffer where the name is */
- /* copied to. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* An error is returned if the face doesn't provide glyph names or if */
- /* the glyph index is invalid. In all cases of failure, the first */
- /* byte of `buffer' is set to~0 to indicate an empty name. */
- /* */
- /* The glyph name is truncated to fit within the buffer if it is too */
- /* long. The returned string is always zero-terminated. */
- /* */
- /* Be aware that FreeType reorders glyph indices internally so that */
- /* glyph index~0 always corresponds to the `missing glyph' (called */
- /* `.notdef'). */
- /* */
- /* This function always returns an error if the config macro */
- /* `FT_CONFIG_OPTION_NO_GLYPH_NAMES' is not defined in `ftoption.h'. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_Glyph_Name
+ *
+ * @description:
+ * Retrieve the ASCII name of a given glyph in a face. This only works
+ * for those faces where @FT_HAS_GLYPH_NAMES(face) returns~1.
+ *
+ * @input:
+ * face ::
+ * A handle to a source face object.
+ *
+ * glyph_index ::
+ * The glyph index.
+ *
+ * buffer_max ::
+ * The maximum number of bytes available in the buffer.
+ *
+ * @output:
+ * buffer ::
+ * A pointer to a target buffer where the name is copied to.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * An error is returned if the face doesn't provide glyph names or if the
+ * glyph index is invalid. In all cases of failure, the first byte of
+ * `buffer` is set to~0 to indicate an empty name.
+ *
+ * The glyph name is truncated to fit within the buffer if it is too
+ * long. The returned string is always zero-terminated.
+ *
+ * Be aware that FreeType reorders glyph indices internally so that glyph
+ * index~0 always corresponds to the 'missing glyph' (called '.notdef').
+ *
+ * This function always returns an error if the config macro
+ * `FT_CONFIG_OPTION_NO_GLYPH_NAMES` is not defined in `ftoption.h`.
+ */
FT_EXPORT( FT_Error )
FT_Get_Glyph_Name( FT_Face face,
FT_UInt glyph_index,
@@ -3537,107 +3570,109 @@ FT_BEGIN_HEADER
FT_UInt buffer_max );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_Postscript_Name */
- /* */
- /* <Description> */
- /* Retrieve the ASCII PostScript name of a given face, if available. */
- /* This only works with PostScript, TrueType, and OpenType fonts. */
- /* */
- /* <Input> */
- /* face :: A handle to the source face object. */
- /* */
- /* <Return> */
- /* A pointer to the face's PostScript name. NULL if unavailable. */
- /* */
- /* <Note> */
- /* The returned pointer is owned by the face and is destroyed with */
- /* it. */
- /* */
- /* For variation fonts, this string changes if you select a different */
- /* instance, and you have to call `FT_Get_PostScript_Name' again to */
- /* retrieve it. FreeType follows Adobe TechNote #5902, `Generating */
- /* PostScript Names for Fonts Using OpenType Font Variations'. */
- /* */
- /* https://download.macromedia.com/pub/developer/opentype/tech-notes/5902.AdobePSNameGeneration.html */
- /* */
- /* [Since 2.9] Special PostScript names for named instances are only */
- /* returned if the named instance is set with @FT_Set_Named_Instance */
- /* (and the font has corresponding entries in its `fvar' table). If */
- /* @FT_IS_VARIATION returns true, the algorithmically derived */
- /* PostScript name is provided, not looking up special entries for */
- /* named instances. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_Postscript_Name
+ *
+ * @description:
+ * Retrieve the ASCII PostScript name of a given face, if available.
+ * This only works with PostScript, TrueType, and OpenType fonts.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * @return:
+ * A pointer to the face's PostScript name. `NULL` if unavailable.
+ *
+ * @note:
+ * The returned pointer is owned by the face and is destroyed with it.
+ *
+ * For variation fonts, this string changes if you select a different
+ * instance, and you have to call `FT_Get_PostScript_Name` again to
+ * retrieve it. FreeType follows Adobe TechNote #5902, 'Generating
+ * PostScript Names for Fonts Using OpenType Font Variations'.
+ *
+ * https://download.macromedia.com/pub/developer/opentype/tech-notes/5902.AdobePSNameGeneration.html
+ *
+ * [Since 2.9] Special PostScript names for named instances are only
+ * returned if the named instance is set with @FT_Set_Named_Instance (and
+ * the font has corresponding entries in its 'fvar' table). If
+ * @FT_IS_VARIATION returns true, the algorithmically derived PostScript
+ * name is provided, not looking up special entries for named instances.
+ */
FT_EXPORT( const char* )
FT_Get_Postscript_Name( FT_Face face );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Select_Charmap */
- /* */
- /* <Description> */
- /* Select a given charmap by its encoding tag (as listed in */
- /* `freetype.h'). */
- /* */
- /* <InOut> */
- /* face :: A handle to the source face object. */
- /* */
- /* <Input> */
- /* encoding :: A handle to the selected encoding. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* This function returns an error if no charmap in the face */
- /* corresponds to the encoding queried here. */
- /* */
- /* Because many fonts contain more than a single cmap for Unicode */
- /* encoding, this function has some special code to select the one */
- /* that covers Unicode best (`best' in the sense that a UCS-4 cmap is */
- /* preferred to a UCS-2 cmap). It is thus preferable to */
- /* @FT_Set_Charmap in this case. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Select_Charmap
+ *
+ * @description:
+ * Select a given charmap by its encoding tag (as listed in
+ * `freetype.h`).
+ *
+ * @inout:
+ * face ::
+ * A handle to the source face object.
+ *
+ * @input:
+ * encoding ::
+ * A handle to the selected encoding.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * This function returns an error if no charmap in the face corresponds
+ * to the encoding queried here.
+ *
+ * Because many fonts contain more than a single cmap for Unicode
+ * encoding, this function has some special code to select the one that
+ * covers Unicode best ('best' in the sense that a UCS-4 cmap is
+ * preferred to a UCS-2 cmap). It is thus preferable to @FT_Set_Charmap
+ * in this case.
+ */
FT_EXPORT( FT_Error )
FT_Select_Charmap( FT_Face face,
FT_Encoding encoding );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Set_Charmap */
- /* */
- /* <Description> */
- /* Select a given charmap for character code to glyph index mapping. */
- /* */
- /* <InOut> */
- /* face :: A handle to the source face object. */
- /* */
- /* <Input> */
- /* charmap :: A handle to the selected charmap. */
- /* */
- /* <Return> */
- /* FreeType error code. 0~means success. */
- /* */
- /* <Note> */
- /* This function returns an error if the charmap is not part of */
- /* the face (i.e., if it is not listed in the `face->charmaps' */
- /* table). */
- /* */
- /* It also fails if an OpenType type~14 charmap is selected (which */
- /* doesn't map character codes to glyph indices at all). */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Set_Charmap
+ *
+ * @description:
+ * Select a given charmap for character code to glyph index mapping.
+ *
+ * @inout:
+ * face ::
+ * A handle to the source face object.
+ *
+ * @input:
+ * charmap ::
+ * A handle to the selected charmap.
+ *
+ * @return:
+ * FreeType error code. 0~means success.
+ *
+ * @note:
+ * This function returns an error if the charmap is not part of the face
+ * (i.e., if it is not listed in the `face->charmaps` table).
+ *
+ * It also fails if an OpenType type~14 charmap is selected (which
+ * doesn't map character codes to glyph indices at all).
+ */
FT_EXPORT( FT_Error )
FT_Set_Charmap( FT_Face face,
FT_CharMap charmap );
- /*************************************************************************
+ /**************************************************************************
*
* @function:
* FT_Get_Charmap_Index
@@ -3651,139 +3686,143 @@ FT_BEGIN_HEADER
*
* @return:
* The index into the array of character maps within the face to which
- * `charmap' belongs. If an error occurs, -1 is returned.
+ * `charmap` belongs. If an error occurs, -1 is returned.
*
*/
FT_EXPORT( FT_Int )
FT_Get_Charmap_Index( FT_CharMap charmap );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_Char_Index */
- /* */
- /* <Description> */
- /* Return the glyph index of a given character code. This function */
- /* uses the currently selected charmap to do the mapping. */
- /* */
- /* <Input> */
- /* face :: A handle to the source face object. */
- /* */
- /* charcode :: The character code. */
- /* */
- /* <Return> */
- /* The glyph index. 0~means `undefined character code'. */
- /* */
- /* <Note> */
- /* If you use FreeType to manipulate the contents of font files */
- /* directly, be aware that the glyph index returned by this function */
- /* doesn't always correspond to the internal indices used within the */
- /* file. This is done to ensure that value~0 always corresponds to */
- /* the `missing glyph'. If the first glyph is not named `.notdef', */
- /* then for Type~1 and Type~42 fonts, `.notdef' will be moved into */
- /* the glyph ID~0 position, and whatever was there will be moved to */
- /* the position `.notdef' had. For Type~1 fonts, if there is no */
- /* `.notdef' glyph at all, then one will be created at index~0 and */
- /* whatever was there will be moved to the last index -- Type~42 */
- /* fonts are considered invalid under this condition. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_Char_Index
+ *
+ * @description:
+ * Return the glyph index of a given character code. This function uses
+ * the currently selected charmap to do the mapping.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * charcode ::
+ * The character code.
+ *
+ * @return:
+ * The glyph index. 0~means 'undefined character code'.
+ *
+ * @note:
+ * If you use FreeType to manipulate the contents of font files directly,
+ * be aware that the glyph index returned by this function doesn't always
+ * correspond to the internal indices used within the file. This is done
+ * to ensure that value~0 always corresponds to the 'missing glyph'. If
+ * the first glyph is not named '.notdef', then for Type~1 and Type~42
+ * fonts, '.notdef' will be moved into the glyph ID~0 position, and
+ * whatever was there will be moved to the position '.notdef' had. For
+ * Type~1 fonts, if there is no '.notdef' glyph at all, then one will be
+ * created at index~0 and whatever was there will be moved to the last
+ * index -- Type~42 fonts are considered invalid under this condition.
+ */
FT_EXPORT( FT_UInt )
FT_Get_Char_Index( FT_Face face,
FT_ULong charcode );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_First_Char */
- /* */
- /* <Description> */
- /* Return the first character code in the current charmap of a given */
- /* face, together with its corresponding glyph index. */
- /* */
- /* <Input> */
- /* face :: A handle to the source face object. */
- /* */
- /* <Output> */
- /* agindex :: Glyph index of first character code. 0~if charmap is */
- /* empty. */
- /* */
- /* <Return> */
- /* The charmap's first character code. */
- /* */
- /* <Note> */
- /* You should use this function together with @FT_Get_Next_Char to */
- /* parse all character codes available in a given charmap. The code */
- /* should look like this: */
- /* */
- /* { */
- /* FT_ULong charcode; */
- /* FT_UInt gindex; */
- /* */
- /* */
- /* charcode = FT_Get_First_Char( face, &gindex ); */
- /* while ( gindex != 0 ) */
- /* { */
- /* ... do something with (charcode,gindex) pair ... */
- /* */
- /* charcode = FT_Get_Next_Char( face, charcode, &gindex ); */
- /* } */
- /* } */
- /* */
- /* Be aware that character codes can have values up to 0xFFFFFFFF; */
- /* this might happen for non-Unicode or malformed cmaps. However, */
- /* even with regular Unicode encoding, so-called `last resort fonts' */
- /* (using SFNT cmap format 13, see function @FT_Get_CMap_Format) */
- /* normally have entries for all Unicode characters up to 0x1FFFFF, */
- /* which can cause *a lot* of iterations. */
- /* */
- /* Note that `*agindex' is set to~0 if the charmap is empty. The */
- /* result itself can be~0 in two cases: if the charmap is empty or */
- /* if the value~0 is the first valid character code. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_First_Char
+ *
+ * @description:
+ * Return the first character code in the current charmap of a given
+ * face, together with its corresponding glyph index.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * @output:
+ * agindex ::
+ * Glyph index of first character code. 0~if charmap is empty.
+ *
+ * @return:
+ * The charmap's first character code.
+ *
+ * @note:
+ * You should use this function together with @FT_Get_Next_Char to parse
+ * all character codes available in a given charmap. The code should
+ * look like this:
+ *
+ * ```
+ * FT_ULong charcode;
+ * FT_UInt gindex;
+ *
+ *
+ * charcode = FT_Get_First_Char( face, &gindex );
+ * while ( gindex != 0 )
+ * {
+ * ... do something with (charcode,gindex) pair ...
+ *
+ * charcode = FT_Get_Next_Char( face, charcode, &gindex );
+ * }
+ * ```
+ *
+ * Be aware that character codes can have values up to 0xFFFFFFFF; this
+ * might happen for non-Unicode or malformed cmaps. However, even with
+ * regular Unicode encoding, so-called 'last resort fonts' (using SFNT
+ * cmap format 13, see function @FT_Get_CMap_Format) normally have
+ * entries for all Unicode characters up to 0x1FFFFF, which can cause *a
+ * lot* of iterations.
+ *
+ * Note that `*agindex` is set to~0 if the charmap is empty. The result
+ * itself can be~0 in two cases: if the charmap is empty or if the
+ * value~0 is the first valid character code.
+ */
FT_EXPORT( FT_ULong )
FT_Get_First_Char( FT_Face face,
FT_UInt *agindex );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_Next_Char */
- /* */
- /* <Description> */
- /* Return the next character code in the current charmap of a given */
- /* face following the value `char_code', as well as the corresponding */
- /* glyph index. */
- /* */
- /* <Input> */
- /* face :: A handle to the source face object. */
- /* */
- /* char_code :: The starting character code. */
- /* */
- /* <Output> */
- /* agindex :: Glyph index of next character code. 0~if charmap */
- /* is empty. */
- /* */
- /* <Return> */
- /* The charmap's next character code. */
- /* */
- /* <Note> */
- /* You should use this function with @FT_Get_First_Char to walk */
- /* over all character codes available in a given charmap. See the */
- /* note for that function for a simple code example. */
- /* */
- /* Note that `*agindex' is set to~0 when there are no more codes in */
- /* the charmap. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_Next_Char
+ *
+ * @description:
+ * Return the next character code in the current charmap of a given face
+ * following the value `char_code`, as well as the corresponding glyph
+ * index.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * char_code ::
+ * The starting character code.
+ *
+ * @output:
+ * agindex ::
+ * Glyph index of next character code. 0~if charmap is empty.
+ *
+ * @return:
+ * The charmap's next character code.
+ *
+ * @note:
+ * You should use this function with @FT_Get_First_Char to walk over all
+ * character codes available in a given charmap. See the note for that
+ * function for a simple code example.
+ *
+ * Note that `*agindex` is set to~0 when there are no more codes in the
+ * charmap.
+ */
FT_EXPORT( FT_ULong )
FT_Get_Next_Char( FT_Face face,
FT_ULong char_code,
FT_UInt *agindex );
- /*************************************************************************
+ /**************************************************************************
*
* @function:
* FT_Face_Properties
@@ -3791,27 +3830,26 @@ FT_BEGIN_HEADER
* @description:
* Set or override certain (library or module-wide) properties on a
* face-by-face basis. Useful for finer-grained control and avoiding
- * locks on shared structures (threads can modify their own faces as
- * they see fit).
+ * locks on shared structures (threads can modify their own faces as they
+ * see fit).
*
- * Contrary to @FT_Property_Set, this function uses @FT_Parameter so
- * that you can pass multiple properties to the target face in one call.
- * Note that only a subset of the available properties can be
- * controlled.
+ * Contrary to @FT_Property_Set, this function uses @FT_Parameter so that
+ * you can pass multiple properties to the target face in one call. Note
+ * that only a subset of the available properties can be controlled.
*
* * @FT_PARAM_TAG_STEM_DARKENING (stem darkening, corresponding to the
- * property `no-stem-darkening' provided by the `autofit', `cff',
- * `type1', and `t1cid' modules; see @no-stem-darkening).
+ * property `no-stem-darkening` provided by the 'autofit', 'cff',
+ * 'type1', and 't1cid' modules; see @no-stem-darkening).
*
* * @FT_PARAM_TAG_LCD_FILTER_WEIGHTS (LCD filter weights, corresponding
* to function @FT_Library_SetLcdFilterWeights).
*
* * @FT_PARAM_TAG_RANDOM_SEED (seed value for the CFF, Type~1, and CID
- * `random' operator, corresponding to the `random-seed' property
- * provided by the `cff', `type1', and `t1cid' modules; see
+ * 'random' operator, corresponding to the `random-seed` property
+ * provided by the 'cff', 'type1', and 't1cid' modules; see
* @random-seed).
*
- * Pass NULL as `data' in @FT_Parameter for a given tag to reset the
+ * Pass `NULL` as `data` in @FT_Parameter for a given tag to reset the
* option and use the library or module default again.
*
* @input:
@@ -3822,17 +3860,17 @@ FT_BEGIN_HEADER
* The number of properties that follow.
*
* properties ::
- * A handle to an @FT_Parameter array with `num_properties' elements.
+ * A handle to an @FT_Parameter array with `num_properties` elements.
*
* @return:
* FreeType error code. 0~means success.
*
- * @note:
- * Here an example that sets three properties. You must define
- * FT_CONFIG_OPTION_SUBPIXEL_RENDERING to make the LCD filter examples
+ * @example:
+ * Here is an example that sets three properties. You must define
+ * `FT_CONFIG_OPTION_SUBPIXEL_RENDERING` to make the LCD filter examples
* work.
*
- * {
+ * ```
* FT_Parameter property1;
* FT_Bool darken_stems = 1;
*
@@ -3858,11 +3896,11 @@ FT_BEGIN_HEADER
* property3.data = &random_seed;
*
* FT_Face_Properties( face, 3, properties );
- * }
+ * ```
*
* The next example resets a single property to its default value.
*
- * {
+ * ```
* FT_Parameter property;
*
*
@@ -3870,7 +3908,7 @@ FT_BEGIN_HEADER
* property.data = NULL;
*
* FT_Face_Properties( face, 1, &property );
- * }
+ * ```
*
* @since:
* 2.8
@@ -3882,37 +3920,40 @@ FT_BEGIN_HEADER
FT_Parameter* properties );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_Name_Index */
- /* */
- /* <Description> */
- /* Return the glyph index of a given glyph name. */
- /* */
- /* <Input> */
- /* face :: A handle to the source face object. */
- /* */
- /* glyph_name :: The glyph name. */
- /* */
- /* <Return> */
- /* The glyph index. 0~means `undefined character code'. */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_Name_Index
+ *
+ * @description:
+ * Return the glyph index of a given glyph name.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * glyph_name ::
+ * The glyph name.
+ *
+ * @return:
+ * The glyph index. 0~means 'undefined character code'.
+ */
FT_EXPORT( FT_UInt )
- FT_Get_Name_Index( FT_Face face,
- FT_String* glyph_name );
+ FT_Get_Name_Index( FT_Face face,
+ const FT_String* glyph_name );
- /*************************************************************************
+ /**************************************************************************
*
- * @macro:
+ * @enum:
* FT_SUBGLYPH_FLAG_XXX
*
* @description:
- * A list of constants describing subglyphs. Please refer to the
- * `glyf' table description in the OpenType specification for the
- * meaning of the various flags (which get synthesized for
- * non-OpenType subglyphs).
+ * A list of constants describing subglyphs. Please refer to the 'glyf'
+ * table description in the OpenType specification for the meaning of the
+ * various flags (which get synthesized for non-OpenType subglyphs).
+ *
+ * https://docs.microsoft.com/en-us/typography/opentype/spec/glyf#composite-glyph-description
*
* @values:
* FT_SUBGLYPH_FLAG_ARGS_ARE_WORDS ::
@@ -3933,15 +3974,15 @@ FT_BEGIN_HEADER
#define FT_SUBGLYPH_FLAG_USE_MY_METRICS 0x200
- /*************************************************************************
+ /**************************************************************************
*
- * @func:
+ * @function:
* FT_Get_SubGlyph_Info
*
* @description:
* Retrieve a description of a given subglyph. Only use it if
- * `glyph->format' is @FT_GLYPH_FORMAT_COMPOSITE; an error is
- * returned otherwise.
+ * `glyph->format` is @FT_GLYPH_FORMAT_COMPOSITE; an error is returned
+ * otherwise.
*
* @input:
* glyph ::
@@ -3949,7 +3990,7 @@ FT_BEGIN_HEADER
*
* sub_index ::
* The index of the subglyph. Must be less than
- * `glyph->num_subglyphs'.
+ * `glyph->num_subglyphs`.
*
* @output:
* p_index ::
@@ -3971,10 +4012,12 @@ FT_BEGIN_HEADER
* FreeType error code. 0~means success.
*
* @note:
- * The values of `*p_arg1', `*p_arg2', and `*p_transform' must be
- * interpreted depending on the flags returned in `*p_flags'. See the
+ * The values of `*p_arg1`, `*p_arg2`, and `*p_transform` must be
+ * interpreted depending on the flags returned in `*p_flags`. See the
* OpenType specification for details.
*
+ * https://docs.microsoft.com/en-us/typography/opentype/spec/glyf#composite-glyph-description
+ *
*/
FT_EXPORT( FT_Error )
FT_Get_SubGlyph_Info( FT_GlyphSlot glyph,
@@ -3986,59 +4029,228 @@ FT_BEGIN_HEADER
FT_Matrix *p_transform );
- /*************************************************************************/
- /* */
- /* <Enum> */
- /* FT_FSTYPE_XXX */
- /* */
- /* <Description> */
- /* A list of bit flags used in the `fsType' field of the OS/2 table */
- /* in a TrueType or OpenType font and the `FSType' entry in a */
- /* PostScript font. These bit flags are returned by */
- /* @FT_Get_FSType_Flags; they inform client applications of embedding */
- /* and subsetting restrictions associated with a font. */
- /* */
- /* See */
- /* https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/FontPolicies.pdf */
- /* for more details. */
- /* */
- /* <Values> */
- /* FT_FSTYPE_INSTALLABLE_EMBEDDING :: */
- /* Fonts with no fsType bit set may be embedded and permanently */
- /* installed on the remote system by an application. */
- /* */
- /* FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING :: */
- /* Fonts that have only this bit set must not be modified, embedded */
- /* or exchanged in any manner without first obtaining permission of */
- /* the font software copyright owner. */
- /* */
- /* FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING :: */
- /* The font may be embedded and temporarily loaded on the remote */
- /* system. Documents containing Preview & Print fonts must be */
- /* opened `read-only'; no edits can be applied to the document. */
- /* */
- /* FT_FSTYPE_EDITABLE_EMBEDDING :: */
- /* The font may be embedded but must only be installed temporarily */
- /* on other systems. In contrast to Preview & Print fonts, */
- /* documents containing editable fonts may be opened for reading, */
- /* editing is permitted, and changes may be saved. */
- /* */
- /* FT_FSTYPE_NO_SUBSETTING :: */
- /* The font may not be subsetted prior to embedding. */
- /* */
- /* FT_FSTYPE_BITMAP_EMBEDDING_ONLY :: */
- /* Only bitmaps contained in the font may be embedded; no outline */
- /* data may be embedded. If there are no bitmaps available in the */
- /* font, then the font is unembeddable. */
- /* */
- /* <Note> */
- /* The flags are ORed together, thus more than a single value can be */
- /* returned. */
- /* */
- /* While the `fsType' flags can indicate that a font may be embedded, */
- /* a license with the font vendor may be separately required to use */
- /* the font in this way. */
- /* */
+ /**************************************************************************
+ *
+ * @section:
+ * layer_management
+ *
+ * @title:
+ * Glyph Layer Management
+ *
+ * @abstract:
+ * Retrieving and manipulating OpenType's 'COLR' table data.
+ *
+ * @description:
+ * The functions described here allow access of colored glyph layer data
+ * in OpenType's 'COLR' tables.
+ */
+
+
+ /**************************************************************************
+ *
+ * @struct:
+ * FT_LayerIterator
+ *
+ * @description:
+ * This iterator object is needed for @FT_Get_Color_Glyph_Layer.
+ *
+ * @fields:
+ * num_layers ::
+ * The number of glyph layers for the requested glyph index. Will be
+ * set by @FT_Get_Color_Glyph_Layer.
+ *
+ * layer ::
+ * The current layer. Will be set by @FT_Get_Color_Glyph_Layer.
+ *
+ * p ::
+ * An opaque pointer into 'COLR' table data. The caller must set this
+ * to `NULL` before the first call of @FT_Get_Color_Glyph_Layer.
+ */
+ typedef struct FT_LayerIterator_
+ {
+ FT_UInt num_layers;
+ FT_UInt layer;
+ FT_Byte* p;
+
+ } FT_LayerIterator;
+
+
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_Color_Glyph_Layer
+ *
+ * @description:
+ * This is an interface to the 'COLR' table in OpenType fonts to
+ * iteratively retrieve the colored glyph layers associated with the
+ * current glyph slot.
+ *
+ * https://docs.microsoft.com/en-us/typography/opentype/spec/colr
+ *
+ * The glyph layer data for a given glyph index, if present, provides an
+ * alternative, multi-colour glyph representation: Instead of rendering
+ * the outline or bitmap with the given glyph index, glyphs with the
+ * indices and colors returned by this function are rendered layer by
+ * layer.
+ *
+ * The returned elements are ordered in the z~direction from bottom to
+ * top; the 'n'th element should be rendered with the associated palette
+ * color and blended on top of the already rendered layers (elements 0,
+ * 1, ..., n-1).
+ *
+ * @input:
+ * face ::
+ * A handle to the parent face object.
+ *
+ * base_glyph ::
+ * The glyph index the colored glyph layers are associated with.
+ *
+ * @inout:
+ * iterator ::
+ * An @FT_LayerIterator object. For the first call you should set
+ * `iterator->p` to `NULL`. For all following calls, simply use the
+ * same object again.
+ *
+ * @output:
+ * aglyph_index ::
+ * The glyph index of the current layer.
+ *
+ * acolor_index ::
+ * The color index into the font face's color palette of the current
+ * layer. The value 0xFFFF is special; it doesn't reference a palette
+ * entry but indicates that the text foreground color should be used
+ * instead (to be set up by the application outside of FreeType).
+ *
+ * The color palette can be retrieved with @FT_Palette_Select.
+ *
+ * @return:
+ * Value~1 if everything is OK. If there are no more layers (or if there
+ * are no layers at all), value~0 gets returned. In case of an error,
+ * value~0 is returned also.
+ *
+ * @note:
+ * This function is necessary if you want to handle glyph layers by
+ * yourself. In particular, functions that operate with @FT_GlyphRec
+ * objects (like @FT_Get_Glyph or @FT_Glyph_To_Bitmap) don't have access
+ * to this information.
+ *
+ * Note that @FT_Render_Glyph is able to handle colored glyph layers
+ * automatically if the @FT_LOAD_COLOR flag is passed to a previous call
+ * to @FT_Load_Glyph. [This is an experimental feature.]
+ *
+ * @example:
+ * ```
+ * FT_Color* palette;
+ * FT_LayerIterator iterator;
+ *
+ * FT_Bool have_layers;
+ * FT_UInt layer_glyph_index;
+ * FT_UInt layer_color_index;
+ *
+ *
+ * error = FT_Palette_Select( face, palette_index, &palette );
+ * if ( error )
+ * palette = NULL;
+ *
+ * iterator.p = NULL;
+ * have_layers = FT_Get_Color_Glyph_Layer( face,
+ * glyph_index,
+ * &layer_glyph_index,
+ * &layer_color_index,
+ * &iterator );
+ *
+ * if ( palette && have_layers )
+ * {
+ * do
+ * {
+ * FT_Color layer_color;
+ *
+ *
+ * if ( layer_color_index == 0xFFFF )
+ * layer_color = text_foreground_color;
+ * else
+ * layer_color = palette[layer_color_index];
+ *
+ * // Load and render glyph `layer_glyph_index', then
+ * // blend resulting pixmap (using color `layer_color')
+ * // with previously created pixmaps.
+ *
+ * } while ( FT_Get_Color_Glyph_Layer( face,
+ * glyph_index,
+ * &layer_glyph_index,
+ * &layer_color_index,
+ * &iterator ) );
+ * }
+ * ```
+ */
+ FT_EXPORT( FT_Bool )
+ FT_Get_Color_Glyph_Layer( FT_Face face,
+ FT_UInt base_glyph,
+ FT_UInt *aglyph_index,
+ FT_UInt *acolor_index,
+ FT_LayerIterator* iterator );
+
+
+ /**************************************************************************
+ *
+ * @section:
+ * base_interface
+ *
+ */
+
+ /**************************************************************************
+ *
+ * @enum:
+ * FT_FSTYPE_XXX
+ *
+ * @description:
+ * A list of bit flags used in the `fsType` field of the OS/2 table in a
+ * TrueType or OpenType font and the `FSType` entry in a PostScript font.
+ * These bit flags are returned by @FT_Get_FSType_Flags; they inform
+ * client applications of embedding and subsetting restrictions
+ * associated with a font.
+ *
+ * See
+ * https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/FontPolicies.pdf
+ * for more details.
+ *
+ * @values:
+ * FT_FSTYPE_INSTALLABLE_EMBEDDING ::
+ * Fonts with no fsType bit set may be embedded and permanently
+ * installed on the remote system by an application.
+ *
+ * FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING ::
+ * Fonts that have only this bit set must not be modified, embedded or
+ * exchanged in any manner without first obtaining permission of the
+ * font software copyright owner.
+ *
+ * FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING ::
+ * The font may be embedded and temporarily loaded on the remote
+ * system. Documents containing Preview & Print fonts must be opened
+ * 'read-only'; no edits can be applied to the document.
+ *
+ * FT_FSTYPE_EDITABLE_EMBEDDING ::
+ * The font may be embedded but must only be installed temporarily on
+ * other systems. In contrast to Preview & Print fonts, documents
+ * containing editable fonts may be opened for reading, editing is
+ * permitted, and changes may be saved.
+ *
+ * FT_FSTYPE_NO_SUBSETTING ::
+ * The font may not be subsetted prior to embedding.
+ *
+ * FT_FSTYPE_BITMAP_EMBEDDING_ONLY ::
+ * Only bitmaps contained in the font may be embedded; no outline data
+ * may be embedded. If there are no bitmaps available in the font,
+ * then the font is unembeddable.
+ *
+ * @note:
+ * The flags are ORed together, thus more than a single value can be
+ * returned.
+ *
+ * While the `fsType` flags can indicate that a font may be embedded, a
+ * license with the font vendor may be separately required to use the
+ * font in this way.
+ */
#define FT_FSTYPE_INSTALLABLE_EMBEDDING 0x0000
#define FT_FSTYPE_RESTRICTED_LICENSE_EMBEDDING 0x0002
#define FT_FSTYPE_PREVIEW_AND_PRINT_EMBEDDING 0x0004
@@ -4047,548 +4259,563 @@ FT_BEGIN_HEADER
#define FT_FSTYPE_BITMAP_EMBEDDING_ONLY 0x0200
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Get_FSType_Flags */
- /* */
- /* <Description> */
- /* Return the `fsType' flags for a font. */
- /* */
- /* <Input> */
- /* face :: A handle to the source face object. */
- /* */
- /* <Return> */
- /* The `fsType' flags, see @FT_FSTYPE_XXX. */
- /* */
- /* <Note> */
- /* Use this function rather than directly reading the `fs_type' field */
- /* in the @PS_FontInfoRec structure, which is only guaranteed to */
- /* return the correct results for Type~1 fonts. */
- /* */
- /* <Since> */
- /* 2.3.8 */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Get_FSType_Flags
+ *
+ * @description:
+ * Return the `fsType` flags for a font.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * @return:
+ * The `fsType` flags, see @FT_FSTYPE_XXX.
+ *
+ * @note:
+ * Use this function rather than directly reading the `fs_type` field in
+ * the @PS_FontInfoRec structure, which is only guaranteed to return the
+ * correct results for Type~1 fonts.
+ *
+ * @since:
+ * 2.3.8
+ */
FT_EXPORT( FT_UShort )
FT_Get_FSType_Flags( FT_Face face );
- /*************************************************************************/
- /* */
- /* <Section> */
- /* glyph_variants */
- /* */
- /* <Title> */
- /* Unicode Variation Sequences */
- /* */
- /* <Abstract> */
- /* The FreeType~2 interface to Unicode Variation Sequences (UVS), */
- /* using the SFNT cmap format~14. */
- /* */
- /* <Description> */
- /* Many characters, especially for CJK scripts, have variant forms. */
- /* They are a sort of grey area somewhere between being totally */
- /* irrelevant and semantically distinct; for this reason, the Unicode */
- /* consortium decided to introduce Variation Sequences (VS), */
- /* consisting of a Unicode base character and a variation selector */
- /* instead of further extending the already huge number of */
- /* characters. */
- /* */
- /* Unicode maintains two different sets, namely `Standardized */
- /* Variation Sequences' and registered `Ideographic Variation */
- /* Sequences' (IVS), collected in the `Ideographic Variation */
- /* Database' (IVD). */
- /* */
- /* https://unicode.org/Public/UCD/latest/ucd/StandardizedVariants.txt */
- /* https://unicode.org/reports/tr37/ */
- /* https://unicode.org/ivd/ */
- /* */
- /* To date (January 2017), the character with the most ideographic */
- /* variations is U+9089, having 32 such IVS. */
- /* */
- /* Three Mongolian Variation Selectors have the values U+180B-U+180D; */
- /* 256 generic Variation Selectors are encoded in the ranges */
- /* U+FE00-U+FE0F and U+E0100-U+E01EF. IVS currently use Variation */
- /* Selectors from the range U+E0100-U+E01EF only. */
- /* */
- /* A VS consists of the base character value followed by a single */
- /* Variation Selector. For example, to get the first variation of */
- /* U+9089, you have to write the character sequence `U+9089 U+E0100'. */
- /* */
- /* Adobe and MS decided to support both standardized and ideographic */
- /* VS with a new cmap subtable (format~14). It is an odd subtable */
- /* because it is not a mapping of input code points to glyphs, but */
- /* contains lists of all variations supported by the font. */
- /* */
- /* A variation may be either `default' or `non-default' for a given */
- /* font. A default variation is the one you will get for that code */
- /* point if you look it up in the standard Unicode cmap. A */
- /* non-default variation is a different glyph. */
- /* */
- /*************************************************************************/
+ /**************************************************************************
+ *
+ * @section:
+ * glyph_variants
+ *
+ * @title:
+ * Unicode Variation Sequences
+ *
+ * @abstract:
+ * The FreeType~2 interface to Unicode Variation Sequences (UVS), using
+ * the SFNT cmap format~14.
+ *
+ * @description:
+ * Many characters, especially for CJK scripts, have variant forms. They
+ * are a sort of grey area somewhere between being totally irrelevant and
+ * semantically distinct; for this reason, the Unicode consortium decided
+ * to introduce Variation Sequences (VS), consisting of a Unicode base
+ * character and a variation selector instead of further extending the
+ * already huge number of characters.
+ *
+ * Unicode maintains two different sets, namely 'Standardized Variation
+ * Sequences' and registered 'Ideographic Variation Sequences' (IVS),
+ * collected in the 'Ideographic Variation Database' (IVD).
+ *
+ * https://unicode.org/Public/UCD/latest/ucd/StandardizedVariants.txt
+ * https://unicode.org/reports/tr37/ https://unicode.org/ivd/
+ *
+ * To date (January 2017), the character with the most ideographic
+ * variations is U+9089, having 32 such IVS.
+ *
+ * Three Mongolian Variation Selectors have the values U+180B-U+180D; 256
+ * generic Variation Selectors are encoded in the ranges U+FE00-U+FE0F
+ * and U+E0100-U+E01EF. IVS currently use Variation Selectors from the
+ * range U+E0100-U+E01EF only.
+ *
+ * A VS consists of the base character value followed by a single
+ * Variation Selector. For example, to get the first variation of
+ * U+9089, you have to write the character sequence `U+9089 U+E0100`.
+ *
+ * Adobe and MS decided to support both standardized and ideographic VS
+ * with a new cmap subtable (format~14). It is an odd subtable because
+ * it is not a mapping of input code points to glyphs, but contains lists
+ * of all variations supported by the font.
+ *
+ * A variation may be either 'default' or 'non-default' for a given font.
+ * A default variation is the one you will get for that code point if you
+ * look it up in the standard Unicode cmap. A non-default variation is a
+ * different glyph.
+ *
+ */
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Face_GetCharVariantIndex */
- /* */
- /* <Description> */
- /* Return the glyph index of a given character code as modified by */
- /* the variation selector. */
- /* */
- /* <Input> */
- /* face :: */
- /* A handle to the source face object. */
- /* */
- /* charcode :: */
- /* The character code point in Unicode. */
- /* */
- /* variantSelector :: */
- /* The Unicode code point of the variation selector. */
- /* */
- /* <Return> */
- /* The glyph index. 0~means either `undefined character code', or */
- /* `undefined selector code', or `no variation selector cmap */
- /* subtable', or `current CharMap is not Unicode'. */
- /* */
- /* <Note> */
- /* If you use FreeType to manipulate the contents of font files */
- /* directly, be aware that the glyph index returned by this function */
- /* doesn't always correspond to the internal indices used within */
- /* the file. This is done to ensure that value~0 always corresponds */
- /* to the `missing glyph'. */
- /* */
- /* This function is only meaningful if */
- /* a) the font has a variation selector cmap sub table, */
- /* and */
- /* b) the current charmap has a Unicode encoding. */
- /* */
- /* <Since> */
- /* 2.3.6 */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Face_GetCharVariantIndex
+ *
+ * @description:
+ * Return the glyph index of a given character code as modified by the
+ * variation selector.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * charcode ::
+ * The character code point in Unicode.
+ *
+ * variantSelector ::
+ * The Unicode code point of the variation selector.
+ *
+ * @return:
+ * The glyph index. 0~means either 'undefined character code', or
+ * 'undefined selector code', or 'no variation selector cmap subtable',
+ * or 'current CharMap is not Unicode'.
+ *
+ * @note:
+ * If you use FreeType to manipulate the contents of font files directly,
+ * be aware that the glyph index returned by this function doesn't always
+ * correspond to the internal indices used within the file. This is done
+ * to ensure that value~0 always corresponds to the 'missing glyph'.
+ *
+ * This function is only meaningful if
+ * a) the font has a variation selector cmap sub table, and
+ * b) the current charmap has a Unicode encoding.
+ *
+ * @since:
+ * 2.3.6
+ */
FT_EXPORT( FT_UInt )
FT_Face_GetCharVariantIndex( FT_Face face,
FT_ULong charcode,
FT_ULong variantSelector );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Face_GetCharVariantIsDefault */
- /* */
- /* <Description> */
- /* Check whether this variation of this Unicode character is the one */
- /* to be found in the `cmap'. */
- /* */
- /* <Input> */
- /* face :: */
- /* A handle to the source face object. */
- /* */
- /* charcode :: */
- /* The character codepoint in Unicode. */
- /* */
- /* variantSelector :: */
- /* The Unicode codepoint of the variation selector. */
- /* */
- /* <Return> */
- /* 1~if found in the standard (Unicode) cmap, 0~if found in the */
- /* variation selector cmap, or -1 if it is not a variation. */
- /* */
- /* <Note> */
- /* This function is only meaningful if the font has a variation */
- /* selector cmap subtable. */
- /* */
- /* <Since> */
- /* 2.3.6 */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Face_GetCharVariantIsDefault
+ *
+ * @description:
+ * Check whether this variation of this Unicode character is the one to
+ * be found in the charmap.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * charcode ::
+ * The character codepoint in Unicode.
+ *
+ * variantSelector ::
+ * The Unicode codepoint of the variation selector.
+ *
+ * @return:
+ * 1~if found in the standard (Unicode) cmap, 0~if found in the variation
+ * selector cmap, or -1 if it is not a variation.
+ *
+ * @note:
+ * This function is only meaningful if the font has a variation selector
+ * cmap subtable.
+ *
+ * @since:
+ * 2.3.6
+ */
FT_EXPORT( FT_Int )
FT_Face_GetCharVariantIsDefault( FT_Face face,
FT_ULong charcode,
FT_ULong variantSelector );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Face_GetVariantSelectors */
- /* */
- /* <Description> */
- /* Return a zero-terminated list of Unicode variation selectors found */
- /* in the font. */
- /* */
- /* <Input> */
- /* face :: */
- /* A handle to the source face object. */
- /* */
- /* <Return> */
- /* A pointer to an array of selector code points, or NULL if there is */
- /* no valid variation selector cmap subtable. */
- /* */
- /* <Note> */
- /* The last item in the array is~0; the array is owned by the */
- /* @FT_Face object but can be overwritten or released on the next */
- /* call to a FreeType function. */
- /* */
- /* <Since> */
- /* 2.3.6 */
- /* */
+ /**************************************************************************
+ *
+ * @function:
+ * FT_Face_GetVariantSelectors
+ *
+ * @description:
+ * Return a zero-terminated list of Unicode variation selectors found in
+ * the font.
+ *
+ * @input:
+ * face ::
+ * A handle to the source face object.
+ *
+ * @return:
+ * A pointer to an array of selector code points, or `NULL` if there is
+ * no valid variation selector cmap subtable.
+ *
+ * @note:
+ * The last item in the array is~0; the array is owned by the @FT_Face
+ * object but can be overwritten or released on the next call to a
+ * FreeType function.
+ *
+ * @since:
+ * 2.3.6
+ */
FT_EXPORT( FT_UInt32* )
FT_Face_GetVariantSelectors( FT_Face face );
- /*************************************************************************/
- /* */
- /* <Function> */
- /* FT_Face_GetVariantsOfChar */
- /* */
- /* <Description> */
- /* Return a zero-terminated list of Unicode variation selectors found */
- /* for the specified character code. */
- /* */
- /* <Input> */
- /* face :: */
- /* A handle to the source face object. */
- /* */
- /* charcode :: */
- /* The character codepoint in Unicode. */
- /* */
- /* <Return> */
- /* A pointer to an array of variation selector code points that are */
- /* active for the given character, or NULL if the corresponding list */
- /* is empty. */
- /* */
- /* <Note> */
- /* The last item in the array is~0; the array is owned by the */