1/* Copyright (c) 2012 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/* From dev/ppb_font_dev.idl modified Thu Mar 28 10:56:39 2013. */
7
8#ifndef PPAPI_C_DEV_PPB_FONT_DEV_H_
9#define PPAPI_C_DEV_PPB_FONT_DEV_H_
10
11#include "ppapi/c/pp_bool.h"
12#include "ppapi/c/pp_instance.h"
13#include "ppapi/c/pp_macros.h"
14#include "ppapi/c/pp_point.h"
15#include "ppapi/c/pp_rect.h"
16#include "ppapi/c/pp_resource.h"
17#include "ppapi/c/pp_size.h"
18#include "ppapi/c/pp_stdint.h"
19#include "ppapi/c/pp_var.h"
20
21#define PPB_FONT_DEV_INTERFACE_0_6 "PPB_Font(Dev);0.6"
22#define PPB_FONT_DEV_INTERFACE PPB_FONT_DEV_INTERFACE_0_6
23
24/**
25 * @file
26 * This file defines the <code>PPB_Font_Dev</code> interface.
27 */
28
29
30/**
31 * @addtogroup Enums
32 * @{
33 */
34typedef enum {
35  /**
36   * Uses the user's default web page font (normally either the default serif
37   * or sans serif font).
38   */
39  PP_FONTFAMILY_DEFAULT = 0,
40  /**
41   * These families will use the default web page font corresponding to the
42   * given family.
43   */
44  PP_FONTFAMILY_SERIF = 1,
45  PP_FONTFAMILY_SANSSERIF = 2,
46  PP_FONTFAMILY_MONOSPACE = 3
47} PP_FontFamily_Dev;
48PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FontFamily_Dev, 4);
49
50/**
51 * Specifies the font weight. Normally users will only use NORMAL or BOLD.
52 */
53typedef enum {
54  PP_FONTWEIGHT_100 = 0,
55  PP_FONTWEIGHT_200 = 1,
56  PP_FONTWEIGHT_300 = 2,
57  PP_FONTWEIGHT_400 = 3,
58  PP_FONTWEIGHT_500 = 4,
59  PP_FONTWEIGHT_600 = 5,
60  PP_FONTWEIGHT_700 = 6,
61  PP_FONTWEIGHT_800 = 7,
62  PP_FONTWEIGHT_900 = 8,
63  PP_FONTWEIGHT_NORMAL = PP_FONTWEIGHT_400,
64  PP_FONTWEIGHT_BOLD = PP_FONTWEIGHT_700
65} PP_FontWeight_Dev;
66PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FontWeight_Dev, 4);
67/**
68 * @}
69 */
70
71/**
72 * @addtogroup Structs
73 * @{
74 */
75struct PP_FontDescription_Dev {
76  /**
77   * Font face name as a string. This can also be an undefined var, in which
78   * case the generic family will be obeyed. If the face is not available on
79   * the system, the browser will attempt to do font fallback or pick a default
80   * font.
81   */
82  struct PP_Var face;
83  /**
84   * When Create()ing a font and the face is an undefined var, the family
85   * specifies the generic font family type to use. If the face is specified,
86   * this will be ignored.
87   *
88   * When Describe()ing a font, the family will be the value you passed in when
89   * the font was created. In other words, if you specify a face name, the
90   * family will not be updated to reflect whether the font name you requested
91   * is serif or sans serif.
92   */
93  PP_FontFamily_Dev family;
94  /**
95   * Size in pixels.
96   *
97   * You can specify 0 to get the default font size. The default font size
98   * may vary depending on the requested font. The typical example is that
99   * the user may have a different font size for the default monospace font to
100   * give it a similar optical size to the proportionally spaced fonts.
101   */
102  uint32_t size;
103  /**
104   * Normally you will use either PP_FONTWEIGHT_NORMAL or PP_FONTWEIGHT_BOLD.
105   */
106  PP_FontWeight_Dev weight;
107  PP_Bool italic;
108  PP_Bool small_caps;
109  /**
110   * Adjustment to apply to letter and word spacing, respectively. Initialize
111   * to 0 to get normal spacing. Negative values bring letters/words closer
112   * together, positive values separate them.
113   */
114  int32_t letter_spacing;
115  int32_t word_spacing;
116  /**
117   * Ensure that this struct is 48-bytes wide by padding the end.  In some
118   * compilers, PP_Var is 8-byte aligned, so those compilers align this struct
119   * on 8-byte boundaries as well and pad it to 16 bytes even without this
120   * padding attribute.  This padding makes its size consistent across
121   * compilers.
122   */
123  int32_t padding;
124};
125PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_FontDescription_Dev, 48);
126
127struct PP_FontMetrics_Dev {
128  int32_t height;
129  int32_t ascent;
130  int32_t descent;
131  int32_t line_spacing;
132  int32_t x_height;
133};
134PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_FontMetrics_Dev, 20);
135
136struct PP_TextRun_Dev {
137  /**
138   * This var must either be a string or a null/undefined var (which will be
139   * treated as a 0-length string).
140   */
141  struct PP_Var text;
142  /**
143   * Set to PP_TRUE if the text is right-to-left.
144   *
145   * When <code>override_direction</code> is false, the browser will perform
146   * the Unicode Bidirectional Algorithm (http://unicode.org/reports/tr9/) on
147   * the text. The value of the <code>rtl</code> flag specifies the
148   * directionality of the surrounding environment. This means that Hebrew
149   * word will always display right to left, even if <code>rtl</code> is false.
150   *
151   * When <code>override_direction</code> is true, no autodetection will be done
152   * and <code>rtl</code> specifies the direction of the text.
153   *
154   * TODO(brettw) note that autodetection with rtl = true is currently
155   * unimplemented.
156   */
157  PP_Bool rtl;
158  /**
159   * Set to PP_TRUE to force the directionality of the text regardless of
160   * content.
161   *
162   * If this flag is set, the browser will skip autodetection of the content
163   * and will display all text in the direction specified by the
164   * <code>rtl</code> flag.
165   */
166  PP_Bool override_direction;
167};
168PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_TextRun_Dev, 24);
169/**
170 * @}
171 */
172
173/**
174 * @addtogroup Interfaces
175 * @{
176 */
177struct PPB_Font_Dev_0_6 {
178  /**
179   * Returns a list of all available font families on the system. You can use
180   * this list to decide whether to Create() a font.
181   *
182   * The return value will be a single string with null characters delimiting
183   * the end of each font name. For example: "Arial\0Courier\0Times\0".
184   *
185   * Returns an undefined var on failure (this typically means you passed an
186   * invalid instance).
187   */
188  struct PP_Var (*GetFontFamilies)(PP_Instance instance);
189  /**
190   * Returns a font which best matches the given description. The return value
191   * will have a non-zero ID on success, or zero on failure.
192   */
193  PP_Resource (*Create)(PP_Instance instance,
194                        const struct PP_FontDescription_Dev* description);
195  /**
196   * Returns PP_TRUE if the given resource is a Font. Returns PP_FALSE if the
197   * resource is invalid or some type other than a Font.
198   */
199  PP_Bool (*IsFont)(PP_Resource resource);
200  /**
201   * Loads the description and metrics of the font into the given structures.
202   * The description will be different than the description the font was
203   * created with since it will be filled with the real values from the font
204   * that was actually selected.
205   *
206   * The PP_Var in the description should be of type Void on input. On output,
207   * this will contain the string and will have a reference count of 1. The
208   * plugin is responsible for calling Release on this var.
209   *
210   * Returns PP_TRUE on success, PP_FALSE if the font is invalid or if the Var
211   * in the description isn't Null (to prevent leaks).
212   */
213  PP_Bool (*Describe)(PP_Resource font,
214                      struct PP_FontDescription_Dev* description,
215                      struct PP_FontMetrics_Dev* metrics);
216  /**
217   * Draws the text to the image buffer.
218   *
219   * The given point represents the baseline of the left edge of the font,
220   * regardless of whether it is left-to-right or right-to-left (in the case of
221   * RTL text, this will actually represent the logical end of the text).
222   *
223   * The clip is optional and may be NULL. In this case, the text will be
224   * clipped to the image.
225   *
226   * The image_data_is_opaque flag indicates whether subpixel antialiasing can
227   * be performed, if it is supported. When the image below the text is
228   * opaque, subpixel antialiasing is supported and you should set this to
229   * PP_TRUE to pick up the user's default preferences. If your plugin is
230   * partially transparent, then subpixel antialiasing is not possible and
231   * grayscale antialiasing will be used instead (assuming the user has
232   * antialiasing enabled at all).
233   */
234  PP_Bool (*DrawTextAt)(PP_Resource font,
235                        PP_Resource image_data,
236                        const struct PP_TextRun_Dev* text,
237                        const struct PP_Point* position,
238                        uint32_t color,
239                        const struct PP_Rect* clip,
240                        PP_Bool image_data_is_opaque);
241  /**
242   * Returns the width of the given string. If the font is invalid or the var
243   * isn't a valid string, this will return -1.
244   *
245   * Note that this function handles complex scripts such as Arabic, combining
246   * accents, etc. so that adding the width of substrings won't necessarily
247   * produce the correct width of the entire string.
248   *
249   * Returns -1 on failure.
250   */
251  int32_t (*MeasureText)(PP_Resource font, const struct PP_TextRun_Dev* text);
252  /**
253   * Returns the character at the given pixel X position from the beginning of
254   * the string. This handles complex scripts such as Arabic, where characters
255   * may be combined or replaced depending on the context. Returns (uint32)-1
256   * on failure.
257   */
258  uint32_t (*CharacterOffsetForPixel)(PP_Resource font,
259                                      const struct PP_TextRun_Dev* text,
260                                      int32_t pixel_position);
261  /**
262   * Returns the horizontal advance to the given character if the string was
263   * placed at the given position. This handles complex scripts such as Arabic,
264   * where characters may be combined or replaced depending on context. Returns
265   * -1 on error.
266   */
267  int32_t (*PixelOffsetForCharacter)(PP_Resource font,
268                                     const struct PP_TextRun_Dev* text,
269                                     uint32_t char_offset);
270};
271
272typedef struct PPB_Font_Dev_0_6 PPB_Font_Dev;
273/**
274 * @}
275 */
276
277#endif  /* PPAPI_C_DEV_PPB_FONT_DEV_H_ */
278
279