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