# -*- coding: utf-8 -*-

# Copyright (c) 2015, Michael Droettboom All rights reserved.

# Redistribution and use in source and binary forms, with or without

# modification, are permitted provided that the following conditions

# are met:

# 1. Redistributions of source code must retain the above copyright

# notice, this list of conditions and the following disclaimer.

# 2. Redistributions in binary form must reproduce the above copyright

# notice, this list of conditions and the following disclaimer in

# the documentation and/or other materials provided with the

# distribution.

# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS

# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE

# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,

# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,

# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN

# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

# POSSIBILITY OF SUCH DAMAGE.

# The views and conclusions contained in the software and

# documentation are those of the authors and should not be interpreted

# as representing official policies, either expressed or implied, of

# the FreeBSD Project.

from __future__ import print_function, unicode_literals, absolute_import

Glyph__init__ = """

Information pertaining to a single glyph.

Notes

-----

If `Face.load_glyph` is called with default flags (see `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).

This image can later be converted into a bitmap by calling

`Glyph.render`.

"""

Glyph_advance = """

The transformed advance width for the glyph (in fractional

pixels). May not be transformed, depending on the value of

`LOAD.IGNORE_TRANSFORM`. As specified with `LOAD.VERTICAL_LAYOUT`, it

uses either the `horiAdvance` or the `vertAdvance` value of `metrics`

field.

"""

Glyph_bitmap = """

Get the `Bitmap` from this `Glyph` if it has been rendered.

"""

Glyph_bitmap_left = """

The bitmap's left bearing expressed in integer pixels. Of course, this

is only valid if the format is `GLYPH_FORMAT.BITMAP`.

"""

Glyph_bitmap_top = """

The bitmap's top bearing expressed in integer pixels. Remember that

this is the distance from the baseline to the top-most glyph scanline,

upwards *y* coordinates being positive. Of course, this is only valid

if the format is `GLYPH_FORMAT.BITMAP`.

"""

Glyph_face = """

The parent face object.

"""

Glyph_format = """

The format of the image in the glyph slot. Typically

`GLYPH_FORMAT.BITMAP`, `GLYPH_FORMAT.OUTLINE`, or

`GLYPH_FORMAT.COMPOSITE`, but others are possible.

See `GLYPH_FORMAT` for the set of available formats.

"""

Glyph_get_cbox = """

Get the glyph's ‘control box’.

The control box encloses all the outline's points, including Bézier

control points. Though it coincides with the exact bounding box for

most glyphs, it can be slightly larger in some situations (like when

rotating an outline which contains Bézier outside arcs).

Computing the control box is very fast, while getting the bounding box

can take much more time as it needs to walk over all segments and arcs

in the outline.

Parameters

----------

mode : int, optional

The mode which indicates how to interpret the returned bounding

box values. For the available options, see `GLYPH_BBOX`.

Returns

-------

bbox : BBox

The glyph coordinate bounding box.

Notes

-----

Coordinates are relative to the glyph origin, using the *y* upwards

convention.

If the glyph has been loaded with `LOAD.NO_SCALE`, `mode` must be set

to `GLYPH_BBOX.UNSCALED` to get unscaled font units in 26.6

fixed-point pixel format.

If the font is tricky and the glyph has been loaded with

`LOAD.NO_SCALE`, the resulting `BBox` is meaningless. To get

reasonable values for the `BBox` it is necessary to load the glyph at

a large ppem value (so that the hinting instructions can properly

shift and scale the subglyphs), then extracting the `BBox` which can

be eventually converted back to font units.

Note that the maximum coordinates are exclusive, which means that one

can compute the width and height of the glyph image as::

width = bbox.xMax - bbox.xMin

height = bbox.yMax - bbox.yMin

Note also that for 26.6 coordinates, if `mode` is set to

`GLYPH_BBOX.GRIDFIT`, the coordinates will also be grid-fitted, which

corresponds to::

bbox.xMin = floor(bbox.xMin)

bbox.yMin = floor(bbox.yMin)

bbox.xMax = ceil(bbox.xMax)

bbox.yMax = ceil(bbox.yMax)

To get the bbox in pixel coordinates, set `mode` to

`GLYPH_BBOX.TRUNCATE`.

To get the bbox in grid-fitted pixel coordinates, set `mode` to

`GLYPH_BBOX.PIXELS`.

"""

Glyph_linear_hori_advance = """

The advance width of the unhinted glyph. Its value is expressed in

fractional pixels, unless `LOAD.LINEAR_DESIGN` is set when loading the

glyph. This field can be important to perform correct WYSIWYG

layout. Only relevant for outline glyphs.

"""

Glyph_linear_vert_advance = """

The advance height of the unhinted glyph. Its value is expressed in

fractional pixels, unless `LOAD.LINEAR_DESIGN` is set when loading the

glyph. This field can be important to perform correct WYSIWYG

layout. Only relevant for outline glyphs.

"""

Glyph_lsb_delta = """

The difference between hinted and unhinted left side bearing.

Valid when autohinting is active. Zero otherwise.

"""

Glyph_metrics = """

The `Glyph_Metrics` of the glyph. The returned values depend on the

last load flags (see the `Face.load_glyph` method) 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.

"""

Glyph_outline = """

The outline descriptor for the current glyph image if its format is

`GLYPH_FORMAT.OUTLINE`. Once a glyph is loaded, `outline` can be

transformed, distorted, embolded, etc.

"""

Glyph_render = """

Convert a given glyph image to a `Bitmap`. It does so by inspecting

the glyph image format, finding the relevant renderer, and invoking

it.

Parameters

----------

render_mode : int, optional

This is the render mode used to render the glyph image into a

bitmap.

See `RENDER_MODE` for the available options.

origin : 2-sequence of floats

The (x, y) origin to translate the glyph image before rendering.

Returns

-------

bitmap : Bitmap

The generated bitmap.

Notes

-----

The selected render mode only affects vector glyphs of a

font. Embedded bitmaps often have a different pixel mode like

`PIXEL_MODE.MONO`. You can use `Bitmap.convert` to transform them

into 8-bit pixmaps.

"""

Glyph_rsb_delta = """

The difference between hinted and unhinted right side bearing

Valid when autohinting is active. Zero otherwise.

"""

Glyph_subglyphs = """

A sequence of all of the subglyphs that make up the glyph.

Empty unless `format` is `GLYPH_FORMAT.COMPOSITE`.

"""

GLYPH_BBOX = """

Indicates how the values of `Glyph.get_cbox` are returned.

- `UNSCALED`: Return unscaled font units.

- `SUBPIXELS`: Return unfitted fractional coordinates.

- `GRIDFIT`: Return grid-fitted factional coordinates.

- `TRUNCATE`: Return coordinates in integer pixels.

- `PIXELS`: Return grid-fitted pixel coordinates.

"""

GLYPH_FORMAT = """

Describes the format of a given glyph image.

Note that this version of FreeType only supports two image formats,

even though future font drivers will be able to register their own

format.

- `NONE`: The value 0 is reserved.

- `COMPOSITE`: The glyph image is a composite of several other

images. This format is only used with `LOAD.NO_RECURSE`, and is

used to report compound glyphs (like accented characters).

- `BITMAP`: The glyph image is a bitmap, and can be described as an

`Bitmap`.

- `OUTLINE`: The glyph image is a vectorial outline made of line

segments and Bézier arcs; it can be described as an `Outline`.

- `PLOTTER`: The glyph image is a vectorial path with no inside and

outside contours. Some Type 1 fonts, like those in the Hershey

family, contain glyphs in this format. These are described as

`Outline`, but FreeType isn't currently capable of rendering them

correctly.

"""

RENDER_MODE = """

Selects a `Bitmap` renderer.

- `NORMAL`: This is the default render mode; it corresponds to 8-bit

anti-aliased bitmaps.

- `LIGHT`: This is equivalent to `RENDER_MODE.NORMAL`. It is only

defined as a separate value because render modes are also used

indirectly to define hinting algorithm selectors. See

`LOAD.TARGET_XXX` for details.

- `MONO`: This mode corresponds to 1-bit bitmaps (with 2 levels of

opacity).

- `LCD`: This mode corresponds to horizontal RGB and BGR sub-pixel

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 `PIXEL_MODE.LCD` mode. On many freetype builds, this

functionality will be disabled due to patent restrictions, in which

case the resulting bitmap will be grayscale.

- `LCD_V`: This mode corresponds to vertical RGB and BGR sub-pixel

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 `PIXEL_MODE.LCD_V` mode. On many

freetype builds, this functionality will be disabled due to patent

restrictions, in which case the resulting bitmap will be grayscale.

"""