summaryrefslogtreecommitdiff
path: root/systems/doc/luatex/luatex-harfbuzz.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-03-15 03:01:24 +0000
committerNorbert Preining <norbert@preining.info>2020-03-15 03:01:24 +0000
commit87cddce361c3b477029d13b27bdaa57190b2d74b (patch)
tree0b8f15ef416645c1438cdc4228a1ddb44691b17c /systems/doc/luatex/luatex-harfbuzz.tex
parent942e56ba7d147d18d379305e76f064cec0aade7d (diff)
CTAN sync 202003150301
Diffstat (limited to 'systems/doc/luatex/luatex-harfbuzz.tex')
-rw-r--r--systems/doc/luatex/luatex-harfbuzz.tex317
1 files changed, 317 insertions, 0 deletions
diff --git a/systems/doc/luatex/luatex-harfbuzz.tex b/systems/doc/luatex/luatex-harfbuzz.tex
new file mode 100644
index 0000000000..c7ed992405
--- /dev/null
+++ b/systems/doc/luatex/luatex-harfbuzz.tex
@@ -0,0 +1,317 @@
+% language=uk
+
+\environment luatex-style
+
+\startcomponent luatex-harfbuzz
+
+\definelayer
+ [hbpage]
+ [width=\paperwidth,
+ height=\paperheight]
+
+
+\setupbackgrounds
+ [page]
+ [background=hbpage,
+ state=start]
+
+
+\startchapter[reference=harfbuzz,title={The HarfBuzz libraries}]
+
+
+\startsection[title={The \type {luaharfbuzz} library}][library=luaharfbuzz]
+
+At the moment the documentation of the library is a raw "html-to-pdf"
+rendering of the \type{index.html} file under \type{luaharfbuzz/docs}
+folder of the source code. The example is almost the verbatim copy
+of the file under \type{luaharfbuzz/examples}.
+\page
+
+
+\dorecurse{17}{%
+\setlayer[hbpage][x=0mm,y=0mm,]{\externalfigure[graphics/luaharfbuzz.pdf][page=\recurselevel]}
+\blank
+\page[empty]
+}
+
+
+\startsubsection[title={Example}]
+
+The example is (a small modification of) the file \type{core_types.lua}
+and it requires the file \type{harfbuzz.lua}; both are
+under \type{luaharfbuzz} folder of the source code.
+The fonts \type{notonastaliq.ttf} and \type{amiri-regular.ttf'} are under
+\type{luaharfbuzz/fonts}.
+
+
+\blank[3*big]
+
+\startbuffer[hbmod]
+local hb = require("luaharfbuzz")
+
+-- special tags
+hb.Tag.NONE = hb.Tag.new()
+
+-- special script codes (ISO 15924)
+hb.Script.COMMON = hb.Script.new("Zyyy")
+hb.Script.INHERITED = hb.Script.new("Zinh")
+hb.Script.UNKNOWN = hb.Script.new("Zzzz")
+hb.Script.INVALID = hb.Script.from_iso15924_tag(hb.Tag.NONE)
+
+-- directions
+hb.Direction.INVALID = hb.Direction.new("invalid")
+hb.Direction.LTR = hb.Direction.new("ltr")
+hb.Direction.RTL = hb.Direction.new("rtl")
+hb.Direction.TTB = hb.Direction.new("ttb")
+hb.Direction.BTT = hb.Direction.new("btt")
+
+-- special languages
+hb.Language.INVALID = hb.Language.new()
+
+hb.shape = function(font, buf, options)
+ options = options or { }
+
+ -- Apply options to buffer if they are set.
+ if options.language then buf:set_language(options.language) end
+ if options.script then buf:set_script(options.script) end
+ if options.direction then buf:set_direction(options.direction) end
+
+ -- Guess segment properties, in case all steps above have failed
+ -- to set the right properties.
+ buf:guess_segment_properties()
+
+ local features = {}
+
+ -- Parse features
+ if type(options.features) == "string" then
+ for fs in string.gmatch(options.features, '([^,]+)') do
+ local feature = hb.Feature.new(fs)
+ if feature then
+ table.insert(features, hb.Feature.new(fs))
+ else
+ error(string.format("Invalid feature string: '%s'", fs))
+ end
+ end
+ elseif type(options.features) == "table" then
+ features = options.features
+ elseif options.features then -- non-nil but not a string or table
+ error("Invalid features option")
+ end
+
+ return hb.shape_full(font,buf,features,options.shapers or {})
+end
+
+-- For backward compatibility
+hb.Buffer.HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES = hb.Buffer.CLUSTER_LEVEL_MONOTONE_GRAPHEMES
+hb.Buffer.HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS = hb.Buffer.CLUSTER_LEVEL_MONOTONE_CHARACTERS
+hb.Buffer.HB_BUFFER_CLUSTER_LEVEL_CHARACTERS = hb.Buffer.CLUSTER_LEVEL_CHARACTERS
+hb.Buffer.HB_BUFFER_CLUSTER_LEVEL_DEFAULT = hb.Buffer.CLUSTER_LEVEL_DEFAULT
+
+hb.Tag.HB_TAG_NONE = hb.Tag.NONE
+
+hb.Script.HB_SCRIPT_COMMON = hb.Script.COMMON
+hb.Script.HB_SCRIPT_INHERITED = hb.Script.INHERITED
+hb.Script.HB_SCRIPT_UNKNOWN = hb.Script.UNKNOWN
+hb.Script.HB_SCRIPT_INVALID = hb.Script.INVALID
+
+hb.Language.HB_LANGUAGE_INVALID = hb.Language.INVALID
+
+hb.Direction.HB_DIRECTION_INVALID = hb.Direction.INVALID
+hb.Direction.HB_DIRECTION_LTR = hb.Direction.LTR
+hb.Direction.HB_DIRECTION_RTL = hb.Direction.RTL
+hb.Direction.HB_DIRECTION_TTB = hb.Direction.TTB
+hb.Direction.HB_DIRECTION_BTT = hb.Direction.BTT
+
+hb.Direction.HB_DIRECTION_IS_VALID = hb.Direction.is_valid
+hb.Direction.HB_DIRECTION_IS_HORIZONTAL = hb.Direction.is_horizontal
+hb.Direction.HB_DIRECTION_IS_VERTICAL = hb.Direction.is_vertical
+hb.Direction.HB_DIRECTION_IS_FORWARD = hb.Direction.is_forward
+hb.Direction.HB_DIRECTION_IS_BACKWARD = hb.Direction.is_backward
+
+hb.Buffer.get_glyph_infos_and_positions = hb.Buffer.get_glyphs
+
+return hb
+
+\stopbuffer
+
+\blank[3*big]
+
+The file \type{harfbuzz.lua}:
+\typebuffer[hbmod]
+
+
+\startbuffer[hbex]
+local harfbuzz = require('harfbuzz')
+
+-- Harfbuzz API Version
+print("Harfbuzz API version", harfbuzz.version())
+
+-- Shapers available
+print("Shapers:", harfbuzz.shapers())
+
+
+-- harfbuzz.Face
+local face = harfbuzz.Face.new('notonastaliq.ttf')
+print('\nFace upem = '..face:get_upem())
+
+-- harfbuzz.Font
+local font = harfbuzz.Font.new(face)
+local xs, xy = font:get_scale()
+print("\nDefault font scale = X: "..xs..", Y: "..xy)
+
+-- harfbuzz.Buffer
+local text = "یہ" -- U+06CC U+06C1
+local buf = harfbuzz.Buffer.new()
+buf:add_utf8(text)
+
+-- harfbuzz.shape (Shapes text)
+print("\nShaping '"..text.."' set with Noto Nastaliq Urdu")
+harfbuzz.shape(font, buf, { language = harfbuzz.Language.new("urd"),
+script = harfbuzz.Script.new("Arab"), direction = harfbuzz.Direction.RTL})
+
+local glyphs = buf:get_glyphs()
+print("No. of glyphs", #glyphs)
+for k,v in pairs(glyphs) do
+ print(k)
+ for k1,v1 in pairs(v) do
+ print("",k1,v1)
+ end
+end
+
+local opts = { language = harfbuzz.Language.new("eng"),
+script = harfbuzz.Script.new("Latn"), direction = harfbuzz.Direction.LTR }
+
+local amiri_face = harfbuzz.Face.new('amiri-regular.ttf')
+local amiri_font = harfbuzz.Font.new(amiri_face)
+
+-- shaping '123' w/o features
+print("\nShaping '123' set with Amiri Regular and no features")
+buf= harfbuzz.Buffer.new()
+buf:add_utf8("123")
+harfbuzz.shape(amiri_font, buf, opts)
+glyphs = buf:get_glyphs()
+for k,v in pairs(glyphs) do
+ print(k)
+ for k1,v1 in pairs(v) do
+ print("",k1,v1)
+ end
+end
+
+
+-- shaping '123' with '+numr' (numerators)
+print("\nShaping '123' set with Amiri Regular with 'numr' feature turned on")
+buf= harfbuzz.Buffer.new()
+buf:add_utf8("123")
+opts.features = "+numr"
+harfbuzz.shape(amiri_font, buf, opts)
+glyphs = buf:get_glyphs()
+for k,v in pairs(glyphs) do
+ print(k)
+ for k1,v1 in pairs(v) do
+ print("",k1,v1)
+ end
+end
+\stopbuffer
+
+The example:
+\typebuffer[hbex]
+
+
+\startbuffer[hbout]
+Harfbuzz API version 2.6.4
+Shapers: graphite2 ot fallback
+
+Face upem = 2048
+
+Default font scale = X: 2048, Y: 2048
+
+Shaping 'یہ' set with Noto Nastaliq Urdu
+No. of glyphs 4
+1
+ flags 1.0
+ cluster 2
+ codepoint 277
+ x_advance 472.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset 0.0
+2
+ cluster 0
+ codepoint 19
+ x_advance 0.0
+ y_advance 0.0
+ x_offset 310.0
+ y_offset -383.0
+3
+ cluster 0
+ codepoint 985
+ x_advance 0.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset 0.0
+4
+ cluster 0
+ codepoint 316
+ x_advance 731.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset -68.0
+
+Shaping '123' set with Amiri Regular and no features
+1
+ cluster 0
+ codepoint 20
+ x_advance 1090.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset 0.0
+2
+ cluster 1
+ codepoint 21
+ x_advance 1090.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset 0.0
+3
+ cluster 2
+ codepoint 22
+ x_advance 1090.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset 0.0
+
+Shaping '123' set with Amiri Regular with 'numr' feature turned on
+1
+ cluster 0
+ codepoint 6673
+ x_advance 600.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset 0.0
+2
+ cluster 1
+ codepoint 6674
+ x_advance 600.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset 0.0
+3
+ cluster 2
+ codepoint 6675
+ x_advance 600.0
+ y_advance 0.0
+ x_offset 0.0
+ y_offset 0.0
+
+\stopbuffer
+
+\blank[3*big]
+The result:
+\typebuffer[hbout]
+
+
+\stopsubsection
+\stopsection
+
+\stopchapter
+\stopcomponent