1/* Copyright (c) 2013 The Chromium Authors. All rights reserved.
2 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
4 */
5
6/**
7 * This file defines the <code>PPB_TrueTypeFont_Dev</code> interface. This
8 * interface exposes font table data for 'sfnt' fonts on the host system. These
9 * include TrueType and OpenType fonts.
10 */
11
12[generate_thunk,thunk_include="ppapi/thunk/ppb_truetype_font_singleton_api.h"]
13
14label Chrome {
15  M26 = 0.1
16};
17
18/**
19 * The PP_TrueTypeFontFamily_Dev defines generic font families. These can be
20 * used to create generic fonts consistent with the user's browser settings.
21 */
22[assert_size(4)]
23enum PP_TrueTypeFontFamily_Dev {
24  /**
25   * For a description of these default families, see the
26   * <a href="http://www.w3.org/TR/css3-fonts/#generic-font-families">
27   * 3.1.1 Generic font families</a> documentation.
28   */
29  PP_TRUETYPEFONTFAMILY_SERIF = 0,
30  PP_TRUETYPEFONTFAMILY_SANSSERIF = 1,
31  PP_TRUETYPEFONTFAMILY_CURSIVE = 2,
32  PP_TRUETYPEFONTFAMILY_FANTASY = 3,
33  PP_TRUETYPEFONTFAMILY_MONOSPACE = 4
34};
35
36/**
37 * The PP_TrueTypeFontStyle_Dev enum defines font styles.
38 */
39[assert_size(4)]
40enum PP_TrueTypeFontStyle_Dev {
41  PP_TRUETYPEFONTSTYLE_NORMAL = 0,
42  PP_TRUETYPEFONTSTYLE_ITALIC = 1
43};
44
45/**
46 * The PP_TrueTypeFontWeight_Dev enum defines font weights.
47 */
48[assert_size(4)]
49enum PP_TrueTypeFontWeight_Dev {
50  PP_TRUETYPEFONTWEIGHT_THIN = 100,
51  PP_TRUETYPEFONTWEIGHT_ULTRALIGHT = 200,
52  PP_TRUETYPEFONTWEIGHT_LIGHT = 300,
53  PP_TRUETYPEFONTWEIGHT_NORMAL = 400,
54  PP_TRUETYPEFONTWEIGHT_MEDIUM = 500,
55  PP_TRUETYPEFONTWEIGHT_SEMIBOLD = 600,
56  PP_TRUETYPEFONTWEIGHT_BOLD = 700,
57  PP_TRUETYPEFONTWEIGHT_ULTRABOLD = 800,
58  PP_TRUETYPEFONTWEIGHT_HEAVY = 900
59};
60
61/**
62 * The PP_TrueTypeFontWidth_Dev enum defines font widths.
63 */
64[assert_size(4)]
65enum PP_TrueTypeFontWidth_Dev {
66  PP_TRUETYPEFONTWIDTH_ULTRACONDENSED = 0,
67  PP_TRUETYPEFONTWIDTH_EXTRACONDENSED = 1,
68  PP_TRUETYPEFONTWIDTH_CONDENSED = 2,
69  PP_TRUETYPEFONTWIDTH_SEMICONDENSED = 3,
70  PP_TRUETYPEFONTWIDTH_NORMAL = 4,
71  PP_TRUETYPEFONTWIDTH_SEMIEXPANDED = 5,
72  PP_TRUETYPEFONTWIDTH_EXPANDED = 6,
73  PP_TRUETYPEFONTWIDTH_EXTRAEXPANDED = 7,
74  PP_TRUETYPEFONTWIDTH_ULTRAEXPANDED = 8
75};
76
77/**
78 * The PP_TrueTypeFontCharset enum defines font character sets.
79 */
80[assert_size(4)]
81enum PP_TrueTypeFontCharset_Dev {
82  PP_TRUETYPEFONTCHARSET_ANSI = 0,
83  PP_TRUETYPEFONTCHARSET_DEFAULT = 1,
84  PP_TRUETYPEFONTCHARSET_SYMBOL = 2,
85  PP_TRUETYPEFONTCHARSET_MAC = 77,
86  PP_TRUETYPEFONTCHARSET_SHIFTJIS = 128,
87  PP_TRUETYPEFONTCHARSET_HANGUL = 129,
88  PP_TRUETYPEFONTCHARSET_JOHAB = 130,
89  PP_TRUETYPEFONTCHARSET_GB2312 =134,
90  PP_TRUETYPEFONTCHARSET_CHINESEBIG5 = 136,
91  PP_TRUETYPEFONTCHARSET_GREEK = 161,
92  PP_TRUETYPEFONTCHARSET_TURKISH = 162,
93  PP_TRUETYPEFONTCHARSET_VIETNAMESE = 163,
94  PP_TRUETYPEFONTCHARSET_HEBREW = 177,
95  PP_TRUETYPEFONTCHARSET_ARABIC = 178,
96  PP_TRUETYPEFONTCHARSET_BALTIC = 186,
97  PP_TRUETYPEFONTCHARSET_RUSSIAN = 204,
98  PP_TRUETYPEFONTCHARSET_THAI = 222,
99  PP_TRUETYPEFONTCHARSET_EASTEUROPE = 238,
100  PP_TRUETYPEFONTCHARSET_OEM = 255
101};
102
103/**
104 * The <code>PP_TrueTypeFontDesc</code> struct describes a TrueType font. It is
105 * passed to Create(), and returned by Describe().
106 */
107[assert_size(40)]
108struct PP_TrueTypeFontDesc_Dev {
109   /**
110   * Font family name as a string. This can also be an undefined var, in which
111   * case the generic family will be obeyed. If the face is not available on
112   * the system, the browser will attempt to do font fallback or pick a default
113   * font.
114   */
115  PP_Var family;
116
117  /** This value specifies a generic font family. If a family name string is
118   * provided when creating a font, this is ignored. */
119  PP_TrueTypeFontFamily_Dev generic_family;
120
121  /** This value specifies the font style. */
122  PP_TrueTypeFontStyle_Dev style;
123
124  /** This value specifies the font weight. */
125  PP_TrueTypeFontWeight_Dev weight;
126
127  /** This value specifies the font width, for condensed or expanded fonts */
128  PP_TrueTypeFontWidth_Dev width;
129
130  /** This value specifies a character set. */
131  PP_TrueTypeFontCharset_Dev charset;
132
133  /**
134   * Ensure that this struct is 40-bytes wide by padding the end.  In some
135   * compilers, PP_Var is 8-byte aligned, so those compilers align this struct
136   * on 8-byte boundaries as well and pad it to 16 bytes even without this
137   * padding attribute.  This padding makes its size consistent across
138   * compilers.
139   */
140  int32_t padding;
141};
142
143interface PPB_TrueTypeFont_Dev {
144  /**
145   * Gets an array of TrueType font family names available on the host.
146   * These names can be used to create a font from a specific family.
147   *
148   * @param[in] instance A <code>PP_Instance</code> requesting the family names.
149   * @param[in] output A <code>PP_ArrayOutput</code> to hold the names.
150   * The output is an array of PP_Vars, each holding a family name.
151   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
152   * completion of GetFontFamilies.
153   *
154   * @return If >= 0, the number of family names returned, otherwise an error
155   * code from <code>pp_errors.h</code>.
156   */
157  [singleton,api=PPB_TrueTypeFont_Singleton_API]
158  int32_t GetFontFamilies([in] PP_Instance instance,
159                          [in] PP_ArrayOutput output,
160                          [in] PP_CompletionCallback callback);
161
162  /**
163   * Gets an array of TrueType font descriptors for a given font family. These
164   * descriptors can be used to create a font in that family and matching the
165   * descriptor attributes.
166   *
167   * @param[in] instance A <code>PP_Instance</code> requesting the font
168   * descriptors.
169   * @param[in] family A <code>PP_Var</code> holding a string specifying the
170   * font family.
171   * @param[in] output A <code>PP_ArrayOutput</code> to hold the descriptors.
172   * The output is an array of <code>PP_TrueTypeFontDesc</code> structs. Each
173   * desc contains a PP_Var for the family name which must be released.
174   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
175   * completion of GetFontsInFamily.
176   *
177   * @return If >= 0, the number of font descriptors returned, otherwise an
178   * error code from <code>pp_errors.h</code>.
179   */
180  [singleton,api=PPB_TrueTypeFont_Singleton_API]
181  int32_t GetFontsInFamily([in] PP_Instance instance,
182                           [in] PP_Var family,
183                           [in] PP_ArrayOutput output,
184                           [in] PP_CompletionCallback callback);
185
186  /**
187   * Creates a font resource matching the given font characteristics. The
188   * resource id will be non-zero on success, or zero on failure.
189   *
190   * @param[in] instance A <code>PP_Instance</code> to own the font.
191   * @param[in] desc A pointer to a <code>PP_TrueTypeFontDesc</code> describing
192   * the font.
193   */
194  PP_Resource Create([in] PP_Instance instance,
195                     [in] PP_TrueTypeFontDesc_Dev desc);
196
197  /**
198   * Determines if the given resource is a TrueType font.
199   *
200   * @param[in] resource A <code>PP_Resource</code> corresponding to a resource.
201   *
202   * @return <code>PP_TRUE</code> if the resource is a
203   * <code>PPB_TrueTypeFont_Dev</code>, <code>PP_FALSE</code> otherwise.
204   */
205  PP_Bool IsTrueTypeFont([in] PP_Resource resource);
206
207  /**
208   * Returns a description of the given font resource. This description may
209   * differ from the description passed to Create, reflecting the host's font
210   * matching and fallback algorithm.
211   *
212   * @param[in] font A <code>PP_Resource</code> corresponding to a font.
213   * @param[out] desc A pointer to a <code>PP_TrueTypeFontDesc</code> to hold
214   * the description. The internal 'family' PP_Var should be set to undefined,
215   * since this function overwrites the <code>PP_TrueTypeFontDesc</code>. After
216   * successful completion, the family will be set to a PP_Var with a single
217   * reference, which the caller must release after use.
218   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
219   * completion of Describe.
220   *
221   * @return A return code from <code>pp_errors.h</code>. If an error code is
222   * returned, the <code>PP_TrueTypeFontDesc</code> will be unchanged.
223   */
224  int32_t Describe([in] PP_Resource font,
225                   [out] PP_TrueTypeFontDesc_Dev desc,
226                   [in] PP_CompletionCallback callback);
227
228  /**
229   * Gets an array of identifying tags for each table in the font. These tags
230   * can be used to request specific tables using GetTable.
231   *
232   * @param[in] font A <code>PP_Resource</code> corresponding to a font.
233   * @param[in] output A <code>PP_ArrayOutput</code> to hold the tags.
234   * The output is an array of 4 byte integers, each representing a table tag.
235   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
236   * completion of GetTableTags.
237   *
238   * @return If >= 0, the number of table tags returned, otherwise an error
239   * code from <code>pp_errors.h</code>.
240   */
241  int32_t GetTableTags([in] PP_Resource font,
242                       [in] PP_ArrayOutput output,
243                       [in] PP_CompletionCallback callback);
244
245  /**
246   * Copies the given font table into client memory.
247   *
248   * @param[in] font A <code>PP_Resource</code> corresponding to a font.
249   * @param[in] table A 4 byte value indicating which table to copy.
250   * For example, 'glyf' will cause the outline table to be copied into the
251   * output array. A zero tag value will cause the entire font to be copied.
252   * @param[in] offset The offset into the font table. Passing an offset
253   * greater than or equal to the table size will succeed with 0 bytes copied.
254   * @param[in] max_data_length The maximum number of bytes to transfer from
255   * <code>offset</code>.
256   * @param[in] output A <code>PP_ArrayOutput</code> to hold the font data.
257   * The output is an array of bytes.
258   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
259   * completion of GetTable.
260   *
261   * @return If >= 0, the table size in bytes, otherwise an error code from
262   * <code>pp_errors.h</code>.
263   */
264  int32_t GetTable([in] PP_Resource font,
265                   [in] uint32_t table,
266                   [in] int32_t offset,
267                   [in] int32_t max_data_length,
268                   [in] PP_ArrayOutput output,
269                   [in] PP_CompletionCallback callback);
270};
271