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