src/ppapi/c/dev/ppb_font_dev.h

   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  */
  34 typedef 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;
  48 PP_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  */
  53 typedef 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;
  66 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FontWeight_Dev, 4);
  67 /**
  68  * @}
  69  */
  70
  71 /**
  72  * @addtogroup Structs
  73  * @{
  74  */
  75 struct 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 };
 125 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_FontDescription_Dev, 48);
 126
 127 struct 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 };
 134 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_FontMetrics_Dev, 20);
 135
 136 struct 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 };
 168 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_TextRun_Dev, 24);
 169 /**
 170  * @}
 171  */
 172
 173 /**
 174  * @addtogroup Interfaces
 175  * @{
 176  */
 177 struct 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
 272 typedef struct PPB_Font_Dev_0_6 PPB_Font_Dev;
 273 /**
 274  * @}
 275  */
 276
 277 #endif  /* PPAPI_C_DEV_PPB_FONT_DEV_H_ */
 278