1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/textandloc/fontservices/textshaperplugin/IcuSource/layout/LEFontInstance.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,557 @@
1.4 +
1.5 +/*
1.6 + *
1.7 + * (C) Copyright IBM Corp. 1998-2005 - All Rights Reserved
1.8 + *
1.9 + */
1.10 +
1.11 +#ifndef __LEFONTINSTANCE_H
1.12 +#define __LEFONTINSTANCE_H
1.13 +
1.14 +#include "LETypes.h"
1.15 +/**
1.16 + * \file
1.17 + * \brief C++ API: Layout Engine Font Instance object
1.18 + */
1.19 +
1.20 +U_NAMESPACE_BEGIN
1.21 +
1.22 +/**
1.23 + * Instances of this class are used by <code>LEFontInstance::mapCharsToGlyphs</code> and
1.24 + * <code>LEFontInstance::mapCharToGlyph</code> to adjust character codes before the character
1.25 + * to glyph mapping process. Examples of this are filtering out control characters
1.26 + * and character mirroring - replacing a character which has both a left and a right
1.27 + * hand form with the opposite form.
1.28 + *
1.29 + * @stable ICU 3.2
1.30 + */
1.31 +class LECharMapper /* not : public UObject because this is an interface/mixin class */
1.32 +{
1.33 +public:
1.34 + /**
1.35 + * Destructor.
1.36 + * @stable ICU 3.2
1.37 + */
1.38 + virtual inline ~LECharMapper() {};
1.39 +
1.40 + /**
1.41 + * This method does the adjustments.
1.42 + *
1.43 + * @param ch - the input character
1.44 + *
1.45 + * @return the adjusted character
1.46 + *
1.47 + * @stable ICU 2.8
1.48 + */
1.49 + virtual LEUnicode32 mapChar(LEUnicode32 ch) const = 0;
1.50 +};
1.51 +
1.52 +/**
1.53 + * This is a forward reference to the class which holds the per-glyph
1.54 + * storage.
1.55 + *
1.56 + * @draft ICU 3.0
1.57 + */
1.58 +class LEGlyphStorage;
1.59 +
1.60 +/**
1.61 + * This is a virtual base class that serves as the interface between a LayoutEngine
1.62 + * and the platform font environment. It allows a LayoutEngine to access font tables, do
1.63 + * character to glyph mapping, and obtain metrics information without knowing any platform
1.64 + * specific details. There are also a few utility methods for converting between points,
1.65 + * pixels and funits. (font design units)
1.66 + *
1.67 + * An instance of an <code>LEFontInstance</code> represents a font at a particular point
1.68 + * size. Each instance can represent either a single physical font, or a composite font.
1.69 + * A composite font is a collection of physical fonts, each of which contains a subset of
1.70 + * the characters contained in the composite font.
1.71 + *
1.72 + * Note: with the exception of <code>getSubFont</code>, the methods in this class only
1.73 + * make sense for a physical font. If you have an <code>LEFontInstance</code> which
1.74 + * represents a composite font you should only call the methods below which have
1.75 + * an <code>LEGlyphID</code>, an <code>LEUnicode</code> or an <code>LEUnicode32</code>
1.76 + * as one of the arguments because these can be used to select a particular subfont.
1.77 + *
1.78 + * Subclasses which implement composite fonts should supply an implementation of these
1.79 + * methods with some default behavior such as returning constant values, or using the
1.80 + * values from the first subfont.
1.81 + *
1.82 + * @draft ICU 3.0
1.83 + */
1.84 +class U_LAYOUT_API LEFontInstance : public UObject
1.85 +{
1.86 +public:
1.87 +
1.88 + /**
1.89 + * This virtual destructor is here so that the subclass
1.90 + * destructors can be invoked through the base class.
1.91 + *
1.92 + * @stable ICU 2.8
1.93 + */
1.94 + virtual inline ~LEFontInstance() {};
1.95 +
1.96 + /**
1.97 + * Get a physical font which can render the given text. For composite fonts,
1.98 + * if there is no single physical font which can render all of the text,
1.99 + * return a physical font which can render an initial substring of the text,
1.100 + * and set the <code>offset</code> parameter to the end of that substring.
1.101 + *
1.102 + * Internally, the LayoutEngine works with runs of text all in the same
1.103 + * font and script, so it is best to call this method with text which is
1.104 + * in a single script, passing the script code in as a hint. If you don't
1.105 + * know the script of the text, you can use zero, which is the script code
1.106 + * for characters used in more than one script.
1.107 + *
1.108 + * The default implementation of this method is intended for instances of
1.109 + * <code>LEFontInstance</code> which represent a physical font. It returns
1.110 + * <code>this</code> and indicates that the entire string can be rendered.
1.111 + *
1.112 + * This method will return a valid <code>LEFontInstance</code> unless you
1.113 + * have passed illegal parameters, or an internal error has been encountered.
1.114 + * For composite fonts, it may return the warning <code>LE_NO_SUBFONT_WARNING</code>
1.115 + * to indicate that the returned font may not be able to render all of
1.116 + * the text. Whenever a valid font is returned, the <code>offset</code> parameter
1.117 + * will be advanced by at least one.
1.118 + *
1.119 + * Subclasses which implement composite fonts must override this method.
1.120 + * Where it makes sense, they should use the script code as a hint to render
1.121 + * characters from the COMMON script in the font which is used for the given
1.122 + * script. For example, if the input text is a series of Arabic words separated
1.123 + * by spaces, and the script code passed in is <code>arabScriptCode</code> you
1.124 + * should return the font used for Arabic characters for all of the input text,
1.125 + * including the spaces. If, on the other hand, the input text contains characters
1.126 + * which cannot be rendered by the font used for Arabic characters, but which can
1.127 + * be rendered by another font, you should return that font for those characters.
1.128 + *
1.129 + * @param chars - the array of Unicode characters.
1.130 + * @param offset - a pointer to the starting offset in the text. On exit this
1.131 + * will be set the the limit offset of the text which can be
1.132 + * rendered using the returned font.
1.133 + * @param limit - the limit offset for the input text.
1.134 + * @param script - the script hint.
1.135 + * @param success - set to an error code if the arguments are illegal, or no font
1.136 + * can be returned for some reason. May also be set to
1.137 + * <code>LE_NO_SUBFONT_WARNING</code> if the subfont which
1.138 + * was returned cannot render all of the text.
1.139 + *
1.140 + * @return an <code>LEFontInstance</code> for the sub font which can render the characters, or
1.141 + * <code>NULL</code> if there is an error.
1.142 + *
1.143 + * @see LEScripts.h
1.144 + *
1.145 + * @stable ICU 3.2
1.146 + */
1.147 + virtual const LEFontInstance *getSubFont(const LEUnicode chars[], le_int32 *offset, le_int32 limit, le_int32 script, LEErrorCode &success) const;
1.148 +
1.149 + //
1.150 + // Font file access
1.151 + //
1.152 +
1.153 + /**
1.154 + * This method reads a table from the font. Note that in general,
1.155 + * it only makes sense to call this method on an <code>LEFontInstance</code>
1.156 + * which represents a physical font - i.e. one which has been returned by
1.157 + * <code>getSubFont()</code>. This is because each subfont in a composite font
1.158 + * will have different tables, and there's no way to know which subfont to access.
1.159 + *
1.160 + * Subclasses which represent composite fonts should always return <code>NULL</code>.
1.161 + *
1.162 + * @param tableTag - the four byte table tag. (e.g. 'cmap')
1.163 + *
1.164 + * @return the address of the table in memory, or <code>NULL</code>
1.165 + * if the table doesn't exist.
1.166 + *
1.167 + * @stable ICU 2.8
1.168 + */
1.169 + virtual const void *getFontTable(LETag tableTag) const = 0;
1.170 +
1.171 + /**
1.172 + * This method is used to determine if the font can
1.173 + * render the given character. This can usually be done
1.174 + * by looking the character up in the font's character
1.175 + * to glyph mapping.
1.176 + *
1.177 + * The default implementation of this method will return
1.178 + * <code>TRUE</code> if <code>mapCharToGlyph(ch)</code>
1.179 + * returns a non-zero value.
1.180 + *
1.181 + * @param ch - the character to be tested
1.182 + *
1.183 + * @return <code>TRUE</code> if the font can render ch.
1.184 + *
1.185 + * @stable ICU 3.2
1.186 + */
1.187 + virtual inline le_bool canDisplay(LEUnicode32 ch) const;
1.188 +
1.189 + /**
1.190 + * This method returns the number of design units in
1.191 + * the font's EM square.
1.192 + *
1.193 + * @return the number of design units pre EM.
1.194 + *
1.195 + * @stable ICU 2.8
1.196 + */
1.197 + virtual le_int32 getUnitsPerEM() const = 0;
1.198 +
1.199 + /**
1.200 + * This method maps an array of character codes to an array of glyph
1.201 + * indices, using the font's character to glyph map.
1.202 + *
1.203 + * The default implementation iterates over all of the characters and calls
1.204 + * <code>mapCharToGlyph(ch, mapper)</code> on each one. It also handles surrogate
1.205 + * characters, storing the glyph ID for the high surrogate, and a deleted glyph (0xFFFF)
1.206 + * for the low surrogate.
1.207 + *
1.208 + * Most sublcasses will not need to implement this method.
1.209 + *
1.210 + * @param chars - the character array
1.211 + * @param offset - the index of the first character
1.212 + * @param count - the number of characters
1.213 + * @param reverse - if <code>TRUE</code>, store the glyph indices in reverse order.
1.214 + * @param mapper - the character mapper.
1.215 + * @param glyphStorage - the object which contains the output glyph array
1.216 + *
1.217 + * @see LECharMapper
1.218 + *
1.219 + * @draft ICU 3.0
1.220 + */
1.221 + virtual void mapCharsToGlyphs(const LEUnicode chars[], le_int32 offset, le_int32 count, le_bool reverse, const LECharMapper *mapper, LEGlyphStorage &glyphStorage) const;
1.222 +
1.223 + /**
1.224 + * This method maps a single character to a glyph index, using the
1.225 + * font's character to glyph map. The default implementation of this
1.226 + * method calls the mapper, and then calls <code>mapCharToGlyph(mappedCh)</code>.
1.227 + *
1.228 + * @param ch - the character
1.229 + * @param mapper - the character mapper
1.230 + *
1.231 + * @return the glyph index
1.232 + *
1.233 + * @see LECharMapper
1.234 + *
1.235 + * @stable ICU 3.2
1.236 + */
1.237 + virtual LEGlyphID mapCharToGlyph(LEUnicode32 ch, const LECharMapper *mapper) const;
1.238 +
1.239 + /**
1.240 + * This method maps a single character to a glyph index, using the
1.241 + * font's character to glyph map. There is no default implementation
1.242 + * of this method because it requires information about the platform
1.243 + * font implementation.
1.244 + *
1.245 + * @param ch - the character
1.246 + *
1.247 + * @return the glyph index
1.248 + *
1.249 + * @stable ICU 3.2
1.250 + */
1.251 + virtual LEGlyphID mapCharToGlyph(LEUnicode32 ch) const = 0;
1.252 +
1.253 + //
1.254 + // Metrics
1.255 + //
1.256 +
1.257 + /**
1.258 + * This method gets the X and Y advance of a particular glyph, in pixels.
1.259 + *
1.260 + * @param glyph - the glyph index
1.261 + * @param advance - the X and Y pixel values will be stored here
1.262 + *
1.263 + * @stable ICU 3.2
1.264 + */
1.265 + virtual void getGlyphAdvance(LEGlyphID glyph, LEPoint &advance) const = 0;
1.266 +
1.267 + /**
1.268 + * This method gets the hinted X and Y pixel coordinates of a particular
1.269 + * point in the outline of the given glyph.
1.270 + *
1.271 + * @param glyph - the glyph index
1.272 + * @param pointNumber - the number of the point
1.273 + * @param point - the point's X and Y pixel values will be stored here
1.274 + *
1.275 + * @return <code>TRUE</code> if the point coordinates could be stored.
1.276 + *
1.277 + * @stable ICU 2.8
1.278 + */
1.279 + virtual le_bool getGlyphPoint(LEGlyphID glyph, le_int32 pointNumber, LEPoint &point) const = 0;
1.280 +
1.281 + /**
1.282 + * This method returns the width of the font's EM square
1.283 + * in pixels.
1.284 + *
1.285 + * @return the pixel width of the EM square
1.286 + *
1.287 + * @stable ICU 2.8
1.288 + */
1.289 + virtual float getXPixelsPerEm() const = 0;
1.290 +
1.291 + /**
1.292 + * This method returns the height of the font's EM square
1.293 + * in pixels.
1.294 + *
1.295 + * @return the pixel height of the EM square
1.296 + *
1.297 + * @stable ICU 2.8
1.298 + */
1.299 + virtual float getYPixelsPerEm() const = 0;
1.300 +
1.301 + /**
1.302 + * This method converts font design units in the
1.303 + * X direction to points.
1.304 + *
1.305 + * @param xUnits - design units in the X direction
1.306 + *
1.307 + * @return points in the X direction
1.308 + *
1.309 + * @stable ICU 3.2
1.310 + */
1.311 + virtual inline float xUnitsToPoints(float xUnits) const;
1.312 +
1.313 + /**
1.314 + * This method converts font design units in the
1.315 + * Y direction to points.
1.316 + *
1.317 + * @param yUnits - design units in the Y direction
1.318 + *
1.319 + * @return points in the Y direction
1.320 + *
1.321 + * @stable ICU 3.2
1.322 + */
1.323 + virtual inline float yUnitsToPoints(float yUnits) const;
1.324 +
1.325 + /**
1.326 + * This method converts font design units to points.
1.327 + *
1.328 + * @param units - X and Y design units
1.329 + * @param points - set to X and Y points
1.330 + *
1.331 + * @stable ICU 3.2
1.332 + */
1.333 + virtual inline void unitsToPoints(LEPoint &units, LEPoint &points) const;
1.334 +
1.335 + /**
1.336 + * This method converts pixels in the
1.337 + * X direction to font design units.
1.338 + *
1.339 + * @param xPixels - pixels in the X direction
1.340 + *
1.341 + * @return font design units in the X direction
1.342 + *
1.343 + * @stable ICU 3.2
1.344 + */
1.345 + virtual inline float xPixelsToUnits(float xPixels) const;
1.346 +
1.347 + /**
1.348 + * This method converts pixels in the
1.349 + * Y direction to font design units.
1.350 + *
1.351 + * @param yPixels - pixels in the Y direction
1.352 + *
1.353 + * @return font design units in the Y direction
1.354 + *
1.355 + * @stable ICU 3.2
1.356 + */
1.357 + virtual inline float yPixelsToUnits(float yPixels) const;
1.358 +
1.359 + /**
1.360 + * This method converts pixels to font design units.
1.361 + *
1.362 + * @param pixels - X and Y pixel
1.363 + * @param units - set to X and Y font design units
1.364 + *
1.365 + * @stable ICU 3.2
1.366 + */
1.367 + virtual inline void pixelsToUnits(LEPoint &pixels, LEPoint &units) const;
1.368 +
1.369 + /**
1.370 + * Get the X scale factor from the font's transform. The default
1.371 + * implementation of <code>transformFunits()</code> will call this method.
1.372 + *
1.373 + * @return the X scale factor.
1.374 + *
1.375 + *
1.376 + * @see transformFunits
1.377 + *
1.378 + * @stable ICU 3.2
1.379 + */
1.380 + virtual float getScaleFactorX() const = 0;
1.381 +
1.382 + /**
1.383 + * Get the Y scale factor from the font's transform. The default
1.384 + * implementation of <code>transformFunits()</code> will call this method.
1.385 + *
1.386 + * @return the Yscale factor.
1.387 + *
1.388 + * @see transformFunits
1.389 + *
1.390 + * @stable ICU 3.2
1.391 + */
1.392 + virtual float getScaleFactorY() const = 0;
1.393 +
1.394 + /**
1.395 + * This method transforms an X, Y point in font design units to a
1.396 + * pixel coordinate, applying the font's transform. The default
1.397 + * implementation of this method calls <code>getScaleFactorX()</code>
1.398 + * and <code>getScaleFactorY()</code>.
1.399 + *
1.400 + * @param xFunits - the X coordinate in font design units
1.401 + * @param yFunits - the Y coordinate in font design units
1.402 + * @param pixels - the tranformed co-ordinate in pixels
1.403 + *
1.404 + * @see getScaleFactorX
1.405 + * @see getScaleFactorY
1.406 + *
1.407 + * @stable ICU 3.2
1.408 + */
1.409 + virtual inline void transformFunits(float xFunits, float yFunits, LEPoint &pixels) const;
1.410 +
1.411 + /**
1.412 + * This is a convenience method used to convert
1.413 + * values in a 16.16 fixed point format to floating point.
1.414 + *
1.415 + * @param fixed - the fixed point value
1.416 + *
1.417 + * @return the floating point value
1.418 + *
1.419 + * @stable ICU 2.8
1.420 + */
1.421 + static inline float fixedToFloat(le_int32 fixed);
1.422 +
1.423 + /**
1.424 + * This is a convenience method used to convert
1.425 + * floating point values to 16.16 fixed point format.
1.426 + *
1.427 + * @param theFloat - the floating point value
1.428 + *
1.429 + * @return the fixed point value
1.430 + *
1.431 + * @stable ICU 2.8
1.432 + */
1.433 + static inline le_int32 floatToFixed(float theFloat);
1.434 +
1.435 + //
1.436 + // These methods won't ever be called by the LayoutEngine,
1.437 + // but are useful for clients of <code>LEFontInstance</code> who
1.438 + // need to render text.
1.439 + //
1.440 +
1.441 + /**
1.442 + * Get the font's ascent.
1.443 + *
1.444 + * @return the font's ascent, in points. This value
1.445 + * will always be positive.
1.446 + *
1.447 + * @stable ICU 3.2
1.448 + */
1.449 + virtual le_int32 getAscent() const = 0;
1.450 +
1.451 + /**
1.452 + * Get the font's descent.
1.453 + *
1.454 + * @return the font's descent, in points. This value
1.455 + * will always be positive.
1.456 + *
1.457 + * @stable ICU 3.2
1.458 + */
1.459 + virtual le_int32 getDescent() const = 0;
1.460 +
1.461 + /**
1.462 + * Get the font's leading.
1.463 + *
1.464 + * @return the font's leading, in points. This value
1.465 + * will always be positive.
1.466 + *
1.467 + * @stable ICU 3.2
1.468 + */
1.469 + virtual le_int32 getLeading() const = 0;
1.470 +
1.471 + /**
1.472 + * Get the line height required to display text in
1.473 + * this font. The default implementation of this method
1.474 + * returns the sum of the ascent, descent, and leading.
1.475 + *
1.476 + * @return the line height, in points. This vaule will
1.477 + * always be positive.
1.478 + *
1.479 + * @stable ICU 3.2
1.480 + */
1.481 + virtual le_int32 getLineHeight() const;
1.482 +
1.483 + /**
1.484 + * ICU "poor man's RTTI", returns a UClassID for the actual class.
1.485 + *
1.486 + * @stable ICU 3.2
1.487 + */
1.488 + virtual UClassID getDynamicClassID() const;
1.489 +
1.490 + /**
1.491 + * ICU "poor man's RTTI", returns a UClassID for this class.
1.492 + *
1.493 + * @stable ICU 3.2
1.494 + */
1.495 + static UClassID getStaticClassID();
1.496 +
1.497 +};
1.498 +
1.499 +inline le_bool LEFontInstance::canDisplay(LEUnicode32 ch) const
1.500 +{
1.501 + return LE_GET_GLYPH(mapCharToGlyph(ch)) != 0;
1.502 +}
1.503 +
1.504 +inline float LEFontInstance::xUnitsToPoints(float xUnits) const
1.505 +{
1.506 + return (xUnits * getXPixelsPerEm()) / (float) getUnitsPerEM();
1.507 +}
1.508 +
1.509 +inline float LEFontInstance::yUnitsToPoints(float yUnits) const
1.510 +{
1.511 + return (yUnits * getYPixelsPerEm()) / (float) getUnitsPerEM();
1.512 +}
1.513 +
1.514 +inline void LEFontInstance::unitsToPoints(LEPoint &units, LEPoint &points) const
1.515 +{
1.516 + points.fX = xUnitsToPoints(units.fX);
1.517 + points.fY = yUnitsToPoints(units.fY);
1.518 +}
1.519 +
1.520 +inline float LEFontInstance::xPixelsToUnits(float xPixels) const
1.521 +{
1.522 + return (xPixels * getUnitsPerEM()) / (float) getXPixelsPerEm();
1.523 +}
1.524 +
1.525 +inline float LEFontInstance::yPixelsToUnits(float yPixels) const
1.526 +{
1.527 + return (yPixels * getUnitsPerEM()) / (float) getYPixelsPerEm();
1.528 +}
1.529 +
1.530 +inline void LEFontInstance::pixelsToUnits(LEPoint &pixels, LEPoint &units) const
1.531 +{
1.532 + units.fX = xPixelsToUnits(pixels.fX);
1.533 + units.fY = yPixelsToUnits(pixels.fY);
1.534 +}
1.535 +
1.536 +inline void LEFontInstance::transformFunits(float xFunits, float yFunits, LEPoint &pixels) const
1.537 +{
1.538 + pixels.fX = xUnitsToPoints(xFunits) * getScaleFactorX();
1.539 + pixels.fY = yUnitsToPoints(yFunits) * getScaleFactorY();
1.540 +}
1.541 +
1.542 +inline float LEFontInstance::fixedToFloat(le_int32 fixed)
1.543 +{
1.544 + return (float) (fixed / 65536.0);
1.545 +}
1.546 +
1.547 +inline le_int32 LEFontInstance::floatToFixed(float theFloat)
1.548 +{
1.549 + return (le_int32) (theFloat * 65536.0);
1.550 +}
1.551 +
1.552 +inline le_int32 LEFontInstance::getLineHeight() const
1.553 +{
1.554 + return getAscent() + getDescent() + getLeading();
1.555 +}
1.556 +
1.557 +U_NAMESPACE_END
1.558 +#endif
1.559 +
1.560 +