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