1 /*
2   ==============================================================================
3 
4    This file is part of the JUCE library.
5    Copyright (c) 2020 - Raw Material Software Limited
6 
7    JUCE is an open source library subject to commercial or open-source
8    licensing.
9 
10    By using JUCE, you agree to the terms of both the JUCE 6 End-User License
11    Agreement and JUCE Privacy Policy (both effective as of the 16th June 2020).
12 
13    End User License Agreement: www.juce.com/juce-6-licence
14    Privacy Policy: www.juce.com/juce-privacy-policy
15 
16    Or: You may also use this code under the terms of the GPL v3 (see
17    www.gnu.org/licenses).
18 
19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
21    DISCLAIMED.
22 
23   ==============================================================================
24 */
25 
26 namespace juce
27 {
28 
29 //==============================================================================
30 /**
31     A typeface represents a size-independent font.
32 
33     This base class is abstract, but calling createSystemTypefaceFor() will return
34     a platform-specific subclass that can be used.
35 
36     The CustomTypeface subclass allow you to build your own typeface, and to
37     load and save it in the JUCE typeface format.
38 
39     Normally you should never need to deal directly with Typeface objects - the Font
40     class does everything you typically need for rendering text.
41 
42     @see CustomTypeface, Font
43 
44     @tags{Graphics}
45 */
46 class JUCE_API  Typeface  : public ReferenceCountedObject
47 {
48 public:
49     //==============================================================================
50     /** A handy typedef for a pointer to a typeface. */
51     using Ptr = ReferenceCountedObjectPtr<Typeface>;
52 
53     //==============================================================================
54     /** Returns the font family of the typeface.
55         @see Font::getTypefaceName
56     */
getName()57     const String& getName() const noexcept      { return name; }
58 
59     //==============================================================================
60     /** Returns the font style of the typeface.
61         @see Font::getTypefaceStyle
62     */
getStyle()63     const String& getStyle() const noexcept     { return style; }
64 
65     //==============================================================================
66     /** Creates a new system typeface. */
67     static Ptr createSystemTypefaceFor (const Font& font);
68 
69     /** Attempts to create a font from some raw font file data (e.g. a TTF or OTF file image).
70         The system will take its own internal copy of the data, so you can free the block once
71         this method has returned.
72     */
73     static Ptr createSystemTypefaceFor (const void* fontFileData, size_t fontFileDataSize);
74 
75     //==============================================================================
76     /** Destructor. */
77     ~Typeface() override;
78 
79     /** Returns true if this typeface can be used to render the specified font.
80         When called, the font will already have been checked to make sure that its name and
81         style flags match the typeface.
82     */
isSuitableForFont(const Font &)83     virtual bool isSuitableForFont (const Font&) const          { return true; }
84 
85     /** Returns the ascent of the font, as a proportion of its height.
86         The height is considered to always be normalised as 1.0, so this will be a
87         value less that 1.0, indicating the proportion of the font that lies above
88         its baseline.
89     */
90     virtual float getAscent() const = 0;
91 
92     /** Returns the descent of the font, as a proportion of its height.
93         The height is considered to always be normalised as 1.0, so this will be a
94         value less that 1.0, indicating the proportion of the font that lies below
95         its baseline.
96     */
97     virtual float getDescent() const = 0;
98 
99     /** Returns the value by which you should multiply a JUCE font-height value to
100         convert it to the equivalent point-size.
101     */
102     virtual float getHeightToPointsFactor() const = 0;
103 
104     /** Measures the width of a line of text.
105         The distance returned is based on the font having an normalised height of 1.0.
106         You should never need to call this directly! Use Font::getStringWidth() instead!
107     */
108     virtual float getStringWidth (const String& text) = 0;
109 
110     /** Converts a line of text into its glyph numbers and their positions.
111         The distances returned are based on the font having an normalised height of 1.0.
112         You should never need to call this directly! Use Font::getGlyphPositions() instead!
113     */
114     virtual void getGlyphPositions (const String& text, Array<int>& glyphs, Array<float>& xOffsets) = 0;
115 
116     /** Returns the outline for a glyph.
117         The path returned will be normalised to a font height of 1.0.
118     */
119     virtual bool getOutlineForGlyph (int glyphNumber, Path& path) = 0;
120 
121     /** Returns a new EdgeTable that contains the path for the given glyph, with the specified transform applied. */
122     virtual EdgeTable* getEdgeTableForGlyph (int glyphNumber, const AffineTransform& transform, float fontHeight);
123 
124     /** Returns true if the typeface uses hinting. */
isHinted()125     virtual bool isHinted() const                           { return false; }
126 
127     //==============================================================================
128     /** Changes the number of fonts that are cached in memory. */
129     static void setTypefaceCacheSize (int numFontsToCache);
130 
131     /** Clears any fonts that are currently cached in memory. */
132     static void clearTypefaceCache();
133 
134     /** On some platforms, this allows a specific path to be scanned.
135         On macOS you can load .ttf and .otf files, otherwise this is only available when using FreeType.
136     */
137     static void scanFolderForFonts (const File& folder);
138 
139     /** Makes an attempt at performing a good overall distortion that will scale a font of
140         the given size to align vertically with the pixel grid. The path should be an unscaled
141         (i.e. normalised to height of 1.0) path for a glyph.
142     */
143     void applyVerticalHintingTransform (float fontHeight, Path& path);
144 
145 protected:
146     //==============================================================================
147     String name, style;
148 
149     Typeface (const String& name, const String& style) noexcept;
150 
151     static Ptr getFallbackTypeface();
152 
153 private:
154     struct HintingParams;
155     std::unique_ptr<HintingParams> hintingParams;
156     CriticalSection hintingLock;
157 
158     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Typeface)
159 };
160 
161 } // namespace juce
162