src/ppapi/api/dev/ppb_truetype_font_dev.idl

   1 /* Copyright (c) 2013 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_TrueTypeFont_Dev</code> interface. This
   8  * interface exposes font table data for 'sfnt' fonts on the host system. These
   9  * include TrueType and OpenType fonts.
  10  */
  11
  12 [generate_thunk,thunk_include="ppapi/thunk/ppb_truetype_font_singleton_api.h"]
  13
  14 label Chrome {
  15   M26 = 0.1
  16 };
  17
  18 /**
  19  * The PP_TrueTypeFontFamily_Dev defines generic font families. These can be
  20  * used to create generic fonts consistent with the user's browser settings.
  21  */
  22 [assert_size(4)]
  23 enum PP_TrueTypeFontFamily_Dev {
  24   /**
  25    * For a description of these default families, see the
  26    * <a href="http://www.w3.org/TR/css3-fonts/#generic-font-families">
  27    * 3.1.1 Generic font families</a> documentation.
  28    */
  29   PP_TRUETYPEFONTFAMILY_SERIF = 0,
  30   PP_TRUETYPEFONTFAMILY_SANSSERIF = 1,
  31   PP_TRUETYPEFONTFAMILY_CURSIVE = 2,
  32   PP_TRUETYPEFONTFAMILY_FANTASY = 3,
  33   PP_TRUETYPEFONTFAMILY_MONOSPACE = 4
  34 };
  35
  36 /**
  37  * The PP_TrueTypeFontStyle_Dev enum defines font styles.
  38  */
  39 [assert_size(4)]
  40 enum PP_TrueTypeFontStyle_Dev {
  41   PP_TRUETYPEFONTSTYLE_NORMAL = 0,
  42   PP_TRUETYPEFONTSTYLE_ITALIC = 1
  43 };
  44
  45 /**
  46  * The PP_TrueTypeFontWeight_Dev enum defines font weights.
  47  */
  48 [assert_size(4)]
  49 enum PP_TrueTypeFontWeight_Dev {
  50   PP_TRUETYPEFONTWEIGHT_THIN = 100,
  51   PP_TRUETYPEFONTWEIGHT_ULTRALIGHT = 200,
  52   PP_TRUETYPEFONTWEIGHT_LIGHT = 300,
  53   PP_TRUETYPEFONTWEIGHT_NORMAL = 400,
  54   PP_TRUETYPEFONTWEIGHT_MEDIUM = 500,
  55   PP_TRUETYPEFONTWEIGHT_SEMIBOLD = 600,
  56   PP_TRUETYPEFONTWEIGHT_BOLD = 700,
  57   PP_TRUETYPEFONTWEIGHT_ULTRABOLD = 800,
  58   PP_TRUETYPEFONTWEIGHT_HEAVY = 900
  59 };
  60
  61 /**
  62  * The PP_TrueTypeFontWidth_Dev enum defines font widths.
  63  */
  64 [assert_size(4)]
  65 enum PP_TrueTypeFontWidth_Dev {
  66   PP_TRUETYPEFONTWIDTH_ULTRACONDENSED = 0,
  67   PP_TRUETYPEFONTWIDTH_EXTRACONDENSED = 1,
  68   PP_TRUETYPEFONTWIDTH_CONDENSED = 2,
  69   PP_TRUETYPEFONTWIDTH_SEMICONDENSED = 3,
  70   PP_TRUETYPEFONTWIDTH_NORMAL = 4,
  71   PP_TRUETYPEFONTWIDTH_SEMIEXPANDED = 5,
  72   PP_TRUETYPEFONTWIDTH_EXPANDED = 6,
  73   PP_TRUETYPEFONTWIDTH_EXTRAEXPANDED = 7,
  74   PP_TRUETYPEFONTWIDTH_ULTRAEXPANDED = 8
  75 };
  76
  77 /**
  78  * The PP_TrueTypeFontCharset enum defines font character sets.
  79  */
  80 [assert_size(4)]
  81 enum PP_TrueTypeFontCharset_Dev {
  82   PP_TRUETYPEFONTCHARSET_ANSI = 0,
  83   PP_TRUETYPEFONTCHARSET_DEFAULT = 1,
  84   PP_TRUETYPEFONTCHARSET_SYMBOL = 2,
  85   PP_TRUETYPEFONTCHARSET_MAC = 77,
  86   PP_TRUETYPEFONTCHARSET_SHIFTJIS = 128,
  87   PP_TRUETYPEFONTCHARSET_HANGUL = 129,
  88   PP_TRUETYPEFONTCHARSET_JOHAB = 130,
  89   PP_TRUETYPEFONTCHARSET_GB2312 =134,
  90   PP_TRUETYPEFONTCHARSET_CHINESEBIG5 = 136,
  91   PP_TRUETYPEFONTCHARSET_GREEK = 161,
  92   PP_TRUETYPEFONTCHARSET_TURKISH = 162,
  93   PP_TRUETYPEFONTCHARSET_VIETNAMESE = 163,
  94   PP_TRUETYPEFONTCHARSET_HEBREW = 177,
  95   PP_TRUETYPEFONTCHARSET_ARABIC = 178,
  96   PP_TRUETYPEFONTCHARSET_BALTIC = 186,
  97   PP_TRUETYPEFONTCHARSET_RUSSIAN = 204,
  98   PP_TRUETYPEFONTCHARSET_THAI = 222,
  99   PP_TRUETYPEFONTCHARSET_EASTEUROPE = 238,
 100   PP_TRUETYPEFONTCHARSET_OEM = 255
 101 };
 102
 103 /**
 104  * The <code>PP_TrueTypeFontDesc</code> struct describes a TrueType font. It is
 105  * passed to Create(), and returned by Describe().
 106  */
 107 [assert_size(40)]
 108 struct PP_TrueTypeFontDesc_Dev {
 109    /**
 110    * Font family name as a string. This can also be an undefined var, in which
 111    * case the generic family will be obeyed. If the face is not available on
 112    * the system, the browser will attempt to do font fallback or pick a default
 113    * font.
 114    */
 115   PP_Var family;
 116
 117   /** This value specifies a generic font family. If a family name string is
 118    * provided when creating a font, this is ignored. */
 119   PP_TrueTypeFontFamily_Dev generic_family;
 120
 121   /** This value specifies the font style. */
 122   PP_TrueTypeFontStyle_Dev style;
 123
 124   /** This value specifies the font weight. */
 125   PP_TrueTypeFontWeight_Dev weight;
 126
 127   /** This value specifies the font width, for condensed or expanded fonts */
 128   PP_TrueTypeFontWidth_Dev width;
 129
 130   /** This value specifies a character set. */
 131   PP_TrueTypeFontCharset_Dev charset;
 132
 133   /**
 134    * Ensure that this struct is 40-bytes wide by padding the end.  In some
 135    * compilers, PP_Var is 8-byte aligned, so those compilers align this struct
 136    * on 8-byte boundaries as well and pad it to 16 bytes even without this
 137    * padding attribute.  This padding makes its size consistent across
 138    * compilers.
 139    */
 140   int32_t padding;
 141 };
 142
 143 interface PPB_TrueTypeFont_Dev {
 144   /**
 145    * Gets an array of TrueType font family names available on the host.
 146    * These names can be used to create a font from a specific family.
 147    *
 148    * @param[in] instance A <code>PP_Instance</code> requesting the family names.
 149    * @param[in] output A <code>PP_ArrayOutput</code> to hold the names.
 150    * The output is an array of PP_Vars, each holding a family name.
 151    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 152    * completion of GetFontFamilies.
 153    *
 154    * @return If >= 0, the number of family names returned, otherwise an error
 155    * code from <code>pp_errors.h</code>.
 156    */
 157   [singleton,api=PPB_TrueTypeFont_Singleton_API]
 158   int32_t GetFontFamilies([in] PP_Instance instance,
 159                           [in] PP_ArrayOutput output,
 160                           [in] PP_CompletionCallback callback);
 161
 162   /**
 163    * Gets an array of TrueType font descriptors for a given font family. These
 164    * descriptors can be used to create a font in that family and matching the
 165    * descriptor attributes.
 166    *
 167    * @param[in] instance A <code>PP_Instance</code> requesting the font
 168    * descriptors.
 169    * @param[in] family A <code>PP_Var</code> holding a string specifying the
 170    * font family.
 171    * @param[in] output A <code>PP_ArrayOutput</code> to hold the descriptors.
 172    * The output is an array of <code>PP_TrueTypeFontDesc</code> structs. Each
 173    * desc contains a PP_Var for the family name which must be released.
 174    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 175    * completion of GetFontsInFamily.
 176    *
 177    * @return If >= 0, the number of font descriptors returned, otherwise an
 178    * error code from <code>pp_errors.h</code>.
 179    */
 180   [singleton,api=PPB_TrueTypeFont_Singleton_API]
 181   int32_t GetFontsInFamily([in] PP_Instance instance,
 182                            [in] PP_Var family,
 183                            [in] PP_ArrayOutput output,
 184                            [in] PP_CompletionCallback callback);
 185
 186   /**
 187    * Creates a font resource matching the given font characteristics. The
 188    * resource id will be non-zero on success, or zero on failure.
 189    *
 190    * @param[in] instance A <code>PP_Instance</code> to own the font.
 191    * @param[in] desc A pointer to a <code>PP_TrueTypeFontDesc</code> describing
 192    * the font.
 193    */
 194   PP_Resource Create([in] PP_Instance instance,
 195                      [in] PP_TrueTypeFontDesc_Dev desc);
 196
 197   /**
 198    * Determines if the given resource is a TrueType font.
 199    *
 200    * @param[in] resource A <code>PP_Resource</code> corresponding to a resource.
 201    *
 202    * @return <code>PP_TRUE</code> if the resource is a
 203    * <code>PPB_TrueTypeFont_Dev</code>, <code>PP_FALSE</code> otherwise.
 204    */
 205   PP_Bool IsTrueTypeFont([in] PP_Resource resource);
 206
 207   /**
 208    * Returns a description of the given font resource. This description may
 209    * differ from the description passed to Create, reflecting the host's font
 210    * matching and fallback algorithm.
 211    *
 212    * @param[in] font A <code>PP_Resource</code> corresponding to a font.
 213    * @param[out] desc A pointer to a <code>PP_TrueTypeFontDesc</code> to hold
 214    * the description. The internal 'family' PP_Var should be set to undefined,
 215    * since this function overwrites the <code>PP_TrueTypeFontDesc</code>. After
 216    * successful completion, the family will be set to a PP_Var with a single
 217    * reference, which the caller must release after use.
 218    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 219    * completion of Describe.
 220    *
 221    * @return A return code from <code>pp_errors.h</code>. If an error code is
 222    * returned, the <code>PP_TrueTypeFontDesc</code> will be unchanged.
 223    */
 224   int32_t Describe([in] PP_Resource font,
 225                    [out] PP_TrueTypeFontDesc_Dev desc,
 226                    [in] PP_CompletionCallback callback);
 227
 228   /**
 229    * Gets an array of identifying tags for each table in the font. These tags
 230    * can be used to request specific tables using GetTable.
 231    *
 232    * @param[in] font A <code>PP_Resource</code> corresponding to a font.
 233    * @param[in] output A <code>PP_ArrayOutput</code> to hold the tags.
 234    * The output is an array of 4 byte integers, each representing a table tag.
 235    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 236    * completion of GetTableTags.
 237    *
 238    * @return If >= 0, the number of table tags returned, otherwise an error
 239    * code from <code>pp_errors.h</code>.
 240    */
 241   int32_t GetTableTags([in] PP_Resource font,
 242                        [in] PP_ArrayOutput output,
 243                        [in] PP_CompletionCallback callback);
 244
 245   /**
 246    * Copies the given font table into client memory.
 247    *
 248    * @param[in] font A <code>PP_Resource</code> corresponding to a font.
 249    * @param[in] table A 4 byte value indicating which table to copy.
 250    * For example, 'glyf' will cause the outline table to be copied into the
 251    * output array. A zero tag value will cause the entire font to be copied.
 252    * @param[in] offset The offset into the font table. Passing an offset
 253    * greater than or equal to the table size will succeed with 0 bytes copied.
 254    * @param[in] max_data_length The maximum number of bytes to transfer from
 255    * <code>offset</code>.
 256    * @param[in] output A <code>PP_ArrayOutput</code> to hold the font data.
 257    * The output is an array of bytes.
 258    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 259    * completion of GetTable.
 260    *
 261    * @return If >= 0, the table size in bytes, otherwise an error code from
 262    * <code>pp_errors.h</code>.
 263    */
 264   int32_t GetTable([in] PP_Resource font,
 265                    [in] uint32_t table,
 266                    [in] int32_t offset,
 267                    [in] int32_t max_data_length,
 268                    [in] PP_ArrayOutput output,
 269                    [in] PP_CompletionCallback callback);
 270 };