1/*
2 * (C) Copyright IBM Corp. 1998-2014 - All Rights Reserved
3 *
4 */
5
6#ifndef __OPENTYPELAYOUTENGINE_H
7#define __OPENTYPELAYOUTENGINE_H
8
9#include "LETypes.h"
10#include "LEGlyphFilter.h"
11#include "LEFontInstance.h"
12#include "LayoutEngine.h"
13#include "LETableReference.h"
14
15#include "GlyphSubstitutionTables.h"
16#include "GlyphDefinitionTables.h"
17#include "GlyphPositioningTables.h"
18
19U_NAMESPACE_BEGIN
20
21/**
22 * OpenTypeLayoutEngine implements complex text layout for OpenType fonts - that is
23 * fonts which have GSUB and GPOS tables associated with them. In order to do this,
24 * the glyph processsing step described for LayoutEngine is further broken into three
25 * steps:
26 *
27 * 1) Character processing - this step analyses the characters and assigns a list of OpenType
28 *    feature tags to each one. It may also change, remove or add characters, and change
29 *    their order.
30 *
31 * 2) Glyph processing - This step performs character to glyph mapping,and uses the GSUB
32 *    table associated with the font to perform glyph substitutions, such as ligature substitution.
33 *
34 * 3) Glyph post processing - in cases where the font doesn't directly contain a GSUB table,
35 *    the previous two steps may have generated "fake" glyph indices to use with a "canned" GSUB
36 *    table. This step turns those glyph indices into actual font-specific glyph indices, and may
37 *    perform any other adjustments requried by the previous steps.
38 *
39 * OpenTypeLayoutEngine will also use the font's GPOS table to apply position adjustments
40 * such as kerning and accent positioning.
41 *
42 * @see LayoutEngine
43 *
44 * @internal
45 */
46class U_LAYOUT_API OpenTypeLayoutEngine : public LayoutEngine
47{
48public:
49    /**
50     * This is the main constructor. It constructs an instance of OpenTypeLayoutEngine for
51     * a particular font, script and language. It takes the GSUB table as a parameter since
52     * LayoutEngine::layoutEngineFactory has to read the GSUB table to know that it has an
53     * OpenType font.
54     *
55     * @param fontInstance - the font
56     * @param scriptCode - the script
57     * @param langaugeCode - the language
58     * @param gsubTable - the GSUB table
59     * @param success - set to an error code if the operation fails
60     *
61     * @see LayoutEngine::layoutEngineFactory
62     * @see ScriptAndLangaugeTags.h for script and language codes
63     *
64     * @internal
65     */
66    OpenTypeLayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode,
67                            le_int32 typoFlags, const LEReferenceTo<GlyphSubstitutionTableHeader> &gsubTable, LEErrorCode &success);
68
69    /**
70     * This constructor is used when the font requires a "canned" GSUB table which can't be known
71     * until after this constructor has been invoked.
72     *
73     * @param fontInstance - the font
74     * @param scriptCode - the script
75     * @param langaugeCode - the language
76     * @param success - set to an error code if the operation fails
77     *
78     * @internal
79     */
80    OpenTypeLayoutEngine(const LEFontInstance *fontInstance, le_int32 scriptCode, le_int32 languageCode,
81			 le_int32 typoFlags, LEErrorCode &success);
82
83    /**
84     * The destructor, virtual for correct polymorphic invocation.
85     *
86     * @internal
87     */
88    virtual ~OpenTypeLayoutEngine();
89
90    /**
91     * A convenience method used to convert the script code into
92     * the four byte script tag required by OpenType.
93	 * For Indic languages where multiple script tags exist,
94	 * the version 1 (old style) tag is returned.
95     *
96     * @param scriptCode - the script code
97     *
98     * @return the four byte script tag
99     *
100     * @internal
101     */
102    static LETag getScriptTag(le_int32 scriptCode);
103    /**
104     * A convenience method used to convert the script code into
105     * the four byte script tag required by OpenType.
106	 * For Indic languages where multiple script tags exist,
107	 * the version 2 tag is returned.
108     *
109     * @param scriptCode - the script code
110     *
111     * @return the four byte script tag
112     *
113     * @internal
114     */
115    static LETag getV2ScriptTag(le_int32 scriptCode);
116
117    /**
118     * A convenience method used to convert the langauge code into
119     * the four byte langauge tag required by OpenType.
120     *
121     * @param languageCode - the language code
122     *
123     * @return the four byte language tag
124     *
125     * @internal
126     */
127    static LETag getLangSysTag(le_int32 languageCode);
128
129    /**
130     * ICU "poor man's RTTI", returns a UClassID for the actual class.
131     *
132     * @deprecated ICU 54. See {@link icu::LayoutEngine}
133     */
134    virtual UClassID getDynamicClassID() const;
135
136    /**
137     * ICU "poor man's RTTI", returns a UClassID for this class.
138     *
139     * @deprecated ICU 54. See {@link icu::LayoutEngine}
140     */
141    static UClassID getStaticClassID();
142
143    /**
144     * The array of language tags, indexed by language code.
145     *
146     * @internal
147     */
148    static const LETag languageTags[];
149
150private:
151
152    /**
153     * This method is used by the constructors to convert the script
154     * and language codes to four byte tags and save them.
155     */
156    void setScriptAndLanguageTags();
157
158    /**
159     * The array of script tags, indexed by script code.
160     */
161    static const LETag scriptTags[];
162
163    /**
164     * apply the typoflags. Only called by the c'tors.
165     */
166    void applyTypoFlags();
167
168protected:
169    /**
170     * A set of "default" features. The default characterProcessing method
171     * will apply all of these features to every glyph.
172     *
173     * @internal
174     */
175    FeatureMask fFeatureMask;
176
177    /**
178     * A set of mappings from feature tags to feature masks. These may
179     * be in the order in which the featues should be applied, but they
180     * don't need to be.
181     *
182     * @internal
183     */
184    const FeatureMap *fFeatureMap;
185
186    /**
187     * The length of the feature map.
188     *
189     * @internal
190     */
191    le_int32 fFeatureMapCount;
192
193    /**
194     * <code>TRUE</code> if the features in the
195     * feature map are in the order in which they
196     * must be applied.
197     *
198     * @internal
199     */
200    le_bool fFeatureOrder;
201
202    /**
203     * The address of the GSUB table.
204     *
205     * @internal
206     */
207    LEReferenceTo<GlyphSubstitutionTableHeader> fGSUBTable;
208
209    /**
210     * The address of the GDEF table.
211     *
212     * @internal
213     */
214    LEReferenceTo<GlyphDefinitionTableHeader> fGDEFTable;
215
216    /**
217     * The address of the GPOS table.
218     *
219     * @internal
220     */
221    LEReferenceTo<GlyphPositioningTableHeader> fGPOSTable;
222
223    /**
224     * An optional filter used to inhibit substitutions
225     * preformed by the GSUB table. This is used for some
226     * "canned" GSUB tables to restrict substitutions to
227     * glyphs that are in the font.
228     *
229     * @internal
230     */
231    LEGlyphFilter *fSubstitutionFilter;
232
233    /**
234     * The four byte script tag.
235     *
236     * @internal
237     */
238    LETag fScriptTag;
239
240    /**
241     * The four byte script tag for V2 fonts.
242     *
243     * @internal
244     */
245    LETag fScriptTagV2;
246
247    /**
248     * The four byte language tag
249     *
250     * @internal
251     */
252    LETag fLangSysTag;
253
254    /**
255     * This method does the OpenType character processing. It assigns the OpenType feature
256     * tags to the characters, and may generate output characters that differ from the input
257     * charcters due to insertions, deletions, or reorderings. In such cases, it will also
258     * generate an output character index array reflecting these changes.
259     *
260     * Subclasses must override this method.
261     *
262     * Input parameters:
263     * @param chars - the input character context
264     * @param offset - the index of the first character to process
265     * @param count - the number of characters to process
266     * @param max - the number of characters in the input context
267     * @param rightToLeft - TRUE if the characters are in a right to left directional run
268     *
269     * Output parameters:
270     * @param outChars - the output character array, if different from the input
271     * @param charIndices - the output character index array
272     * @param featureTags - the output feature tag array
273     * @param success - set to an error code if the operation fails
274     *
275     * @return the output character count (input character count if no change)
276     *
277     * @internal
278     */
279    virtual le_int32 characterProcessing(const LEUnicode /*chars*/[], le_int32 offset, le_int32 count, le_int32 max, le_bool /*rightToLeft*/,
280            LEUnicode *&/*outChars*/, LEGlyphStorage &glyphStorage, LEErrorCode &success);
281
282    /**
283     * This method does character to glyph mapping, and applies the GSUB table. The
284     * default implementation calls mapCharsToGlyphs and then applies the GSUB table,
285     * if there is one.
286     *
287     * Note that in the case of "canned" GSUB tables, the output glyph indices may be
288     * "fake" glyph indices that need to be converted to "real" glyph indices by the
289     * glyphPostProcessing method.
290     *
291     * Input parameters:
292     * @param chars - the input character context
293     * @param offset - the index of the first character to process
294     * @param count - the number of characters to process
295     * @param max - the number of characters in the input context
296     * @param rightToLeft - TRUE if the characters are in a right to left directional run
297     * @param featureTags - the feature tag array
298     *
299     * Output parameters:
300     * @param glyphs - the output glyph index array
301     * @param charIndices - the output character index array
302     * @param success - set to an error code if the operation fails
303     *
304     * @return the number of glyphs in the output glyph index array
305     *
306     * Note: if the character index array was already set by the characterProcessing
307     * method, this method won't change it.
308     *
309     * @internal
310     */
311    virtual le_int32 glyphProcessing(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft,
312            LEGlyphStorage &glyphStorage, LEErrorCode &success);
313
314    virtual le_int32 glyphSubstitution(le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);
315
316    /**
317     * This method does any processing necessary to convert "fake"
318     * glyph indices used by the glyphProcessing method into "real" glyph
319     * indices which can be used to render the text. Note that in some
320     * cases, such as CDAC Indic fonts, several "real" glyphs may be needed
321     * to render one "fake" glyph.
322     *
323     * The default implementation of this method just returns the input glyph
324     * index and character index arrays, assuming that no "fake" glyph indices
325     * were needed to do GSUB processing.
326     *
327     * Input paramters:
328     * @param tempGlyphs - the input "fake" glyph index array
329     * @param tempCharIndices - the input "fake" character index array
330     * @param tempGlyphCount - the number of "fake" glyph indices
331     *
332     * Output parameters:
333     * @param glyphs - the output glyph index array
334     * @param charIndices - the output character index array
335     * @param success - set to an error code if the operation fails
336     *
337     * @return the number of glyph indices in the output glyph index array
338     *
339     * @internal
340     */
341    virtual le_int32 glyphPostProcessing(LEGlyphStorage &tempGlyphStorage, LEGlyphStorage &glyphStorage, LEErrorCode &success);
342
343    /**
344     * This method applies the characterProcessing, glyphProcessing and glyphPostProcessing
345     * methods. Most subclasses will not need to override this method.
346     *
347     * Input parameters:
348     * @param chars - the input character context
349     * @param offset - the index of the first character to process
350     * @param count - the number of characters to process
351     * @param max - the number of characters in the input context
352     * @param rightToLeft - TRUE if the text is in a right to left directional run
353     *
354     * Output parameters:
355     * @param glyphs - the glyph index array
356     * @param charIndices - the character index array
357     * @param success - set to an error code if the operation fails
358     *
359     * @return the number of glyphs in the glyph index array
360     *
361     * @see LayoutEngine::computeGlyphs
362     *
363     * @internal
364     */
365    virtual le_int32 computeGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_int32 max, le_bool rightToLeft, LEGlyphStorage &glyphStorage, LEErrorCode &success);
366
367    /**
368     * This method uses the GPOS table, if there is one, to adjust the glyph positions.
369     *
370     * Input parameters:
371     * @param glyphs - the input glyph array
372     * @param glyphCount - the number of glyphs in the glyph array
373     * @param x - the starting X position
374     * @param y - the starting Y position
375     *
376     * Output parameters:
377     * @param positions - the output X and Y positions (two entries per glyph)
378     * @param success - set to an error code if the operation fails
379     *
380     * @internal
381     */
382    virtual void adjustGlyphPositions(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, LEGlyphStorage &glyphStorage, LEErrorCode &success);
383
384    /**
385     * This method frees the feature tag array so that the
386     * OpenTypeLayoutEngine can be reused for different text.
387     * It is also called from our destructor.
388     *
389     * @internal
390     */
391    virtual void reset();
392};
393
394U_NAMESPACE_END
395#endif
396
397