/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */

/**
 * This file contains the <code>PPB_Flash</code> interface.
 */

label Chrome {
  M17 = 12.0,
  M19 = 12.1,
  M20_0 = 12.2,
  M20_1 = 12.3,
  M21 = 12.4
};

[assert_size(4)]
enum PP_FlashSetting {
  /**
   * Specifies if the system likely supports 3D hardware acceleration.
   *
   * The result is a boolean PP_Var, depending on the supported nature of 3D
   * acceleration. If querying this function returns true, the 3D system will
   * normally use the native hardware for rendering which will be much faster.
   *
   * Having this set to true only means that 3D should be used to draw 2D and
   * video elements. PP_FLASHSETTING_STAGE3D_ENABLED should be checked to
   * determine if it's ok to use 3D for arbitrary content.
   *
   * In rare cases (depending on the platform) this value will be true but a
   * created 3D context will use emulation because context initialization
   * failed.
   */
  PP_FLASHSETTING_3DENABLED = 1,

  /**
   * Specifies if the given instance is in private/inconito/off-the-record mode
   * (returns true) or "regular" mode (returns false). Returns an undefined
   * PP_Var on invalid instance.
   */
  PP_FLASHSETTING_INCOGNITO = 2,

  /**
   * Specifies if arbitrary 3d commands are supported (returns true), or if 3d
   * should only be used for drawing 2d and video (returns false).
   *
   * This should only be enabled if PP_FLASHSETTING_3DENABLED is true.
   */
  PP_FLASHSETTING_STAGE3DENABLED = 3,

  /**
   * Specifies the string for the language code of the UI of the browser.
   *
   * For example: "en-US" or "de".
   *
   * Returns an undefined PP_Var on invalid instance.
   */
  PP_FLASHSETTING_LANGUAGE = 4
};

/**
 * The <code>PPB_Flash</code> interface contains pointers to various functions
 * that are only needed to support Pepper Flash.
 */
interface PPB_Flash {
  /**
   * Sets or clears the rendering hint that the given plugin instance is always
   * on top of page content. Somewhat more optimized painting can be used in
   * this case.
   */
  void SetInstanceAlwaysOnTop(
      [in] PP_Instance instance,
      [in] PP_Bool on_top);

  /**
   * Draws the given pre-laid-out text. It is almost equivalent to Windows'
   * ExtTextOut with the addition of the transformation (a 3x3 matrix given the
   * transform to apply before drawing). It also adds the allow_subpixel_aa
   * flag which when true, will use subpixel antialiasing if enabled in the
   * system settings. For this to work properly, the graphics layer that the
   * text is being drawn into must be opaque.
   */
  PP_Bool DrawGlyphs(
      [in] PP_Instance instance,
      [in] PP_Resource pp_image_data,
      [in] PP_FontDescription_Dev font_desc,
      [in] uint32_t color,
      [in] PP_Point position,
      [in] PP_Rect clip,
      [in] float_t[3][3] transformation,
      [in] PP_Bool allow_subpixel_aa,
      [in] uint32_t glyph_count,
      [in, size_is(glyph_count)] uint16_t[] glyph_indices,
      [in, size_is(glyph_count)] PP_Point[] glyph_advances);

  /**
   * Retrieves the proxy that will be used for the given URL. The result will
   * be a string in PAC format, or an undefined var on error.
   */
  PP_Var GetProxyForURL(
      [in] PP_Instance instance,
      [in] str_t url);

  /**
   * Navigate to the URL given by the given URLRequestInfo. (This supports GETs,
   * POSTs, and javascript: URLs.) May open a new tab if target is not "_self".
   */
  int32_t Navigate(
      [in] PP_Resource request_info,
      [in] str_t target,
      [in] PP_Bool from_user_action);

  /**
   * Runs a nested message loop. The plugin will be reentered from this call.
   * This function is used in places where Flash would normally enter a nested
   * message loop (e.g., when displaying context menus), but Pepper provides
   * only an asynchronous call. After performing that asynchronous call, call
   * |RunMessageLoop()|. In the callback, call |QuitMessageLoop()|.
   */
  void RunMessageLoop(
      [in] PP_Instance instance);

  /* Posts a quit message for the outermost nested message loop. Use this to
   * exit and return back to the caller after you call RunMessageLoop.
   */
  void QuitMessageLoop(
      [in] PP_Instance instance);

  /**
   * Retrieves the local time zone offset from GM time for the given UTC time.
   */
  double_t GetLocalTimeZoneOffset(
      [in] PP_Instance instance,
      [in] PP_Time t);

  /**
   * Gets a (string) with "command-line" options for Flash; used to pass
   * run-time debugging parameters, etc.
   */
  PP_Var GetCommandLineArgs(
      [in] PP_Module module);

  /**
   * Loads the given font in a more priviledged process on Windows. Call this if
   * Windows is giving errors for font calls. See
   * content/renderer/font_cache_dispatcher_win.cc
   *
   * The parameter is a pointer to a LOGFONTW structure.
   *
   * On non-Windows platforms, this function does nothing.
   */
  void PreloadFontWin(
      [in] mem_t logfontw);

  /**
   * Returns whether the given rectangle (in the plugin) is topmost, i.e., above
   * all other web content.
   */
  [version=12.1]
  PP_Bool IsRectTopmost(
      [in] PP_Instance instance,
      [in] PP_Rect rect);

  /**
   * Does nothing, deprecated. See PPB_Flash_Print.
   */
  [version=12.1]
  int32_t InvokePrinting(
      [in] PP_Instance instance);

  /**
   * Indicates that there's activity and, e.g., the screensaver shouldn't kick
   * in.
   */
  [version=12.1]
  void UpdateActivity(
      [in] PP_Instance instance);

  /**
   * Returns the device ID as a string. Returns a PP_VARTYPE_UNDEFINED on error.
   * Deprecated, use GetDeviceIDAsync.
   */
  [version=12.2]
  PP_Var GetDeviceID([in] PP_Instance instance);

  /**
   * Deprecated. See GetSetting().
   */
  [version=12.3]
  int32_t GetSettingInt([in] PP_Instance instance,
                        [in] PP_FlashSetting setting);

  /**
   * Returns the value associated with the given setting. Invalid enums will
   * result in an undefined PP_Var return value.
   */
  [version=12.4]
  PP_Var GetSetting(PP_Instance instance, PP_FlashSetting setting);
};