|
|
| Line 3: |
Line 3: |
| Accepted, ready for implementation. | | Accepted, ready for implementation. |
|
| |
|
| == This Document == | | == Contributors == |
|
| |
|
| This proposal was written by Tim Omernick of Apple Computer, Inc. and posted to the plugin-futures (@mozilla.org) mailing list. It has been formatted here by Josh Aas of Mozilla Corporation.
| | * Last modified: April 22, 2010 |
| | * Authors: Tim Omernick (Apple) |
| | * Contributors: Josh Aas (Mozilla Corporation) |
|
| |
|
| == Overview == | | == Overview == |
|
| |
|
| Part of what made Apple's transition from Mac OS 9 to Mac OS X so smooth was that we provided backward-compatible APIs, like QuickDraw, so developers did not need to rewrite their applications for the new platform. Unfortunately, this plan worked a little bit too well -- some apps, including Netscape plugins, were never updated to use the modern APIs!
| | Quickdraw is deprecated in 32-bit Mac OS X and entirely gone in 64-bit Mac OS X. The Core Graphics drawing model is an alternative drawing model for 32-bit Mac OS X plugins, and the default drawing model for 64-bit Mac OS X plugins. |
|
| |
|
| The Netscape Plugin API is showing its age. It assumes that browsers and plugins use QuickDraw, and that QuickDraw is the only way to draw. On Mac OS X, however, QuickDraw is a second-class citizen. It is a pain for a modern Mac browser to host Netscape plugins, because it must create and maintain a QuickDraw port for the sole purpose of hosting legacy plugins.
| | == Negotiating Core Graphics Drawing == |
|
| |
|
| This problem is about to get worse in two ways:
| | For documentation on negotiating drawing models, see [[NPAPI:Models]]. The drawing model variables for Core Graphics are: |
|
| |
|
| 1) QuickDraw is deprecated, and has been for some time. While it is sticking around for a while longer, it will probably be removed in a future version of Mac OS X.
| | * NPDrawingModelCoreGraphics |
| | * NPNVsupportsCoreGraphicsBool |
|
| |
|
| 2) Many of Apple's frameworks and libraries are being updated for 64-bit. QuickDraw is not invited to the 64-bit party. There will be no 64-bit QuickDraw.
| | == Excluding QuickDraw == |
| | |
| Our proposed solution is to change the Mac Netscape Plugin API (NPAPI) so that it is graphics-API agnostic. That is, plugins are free to use whatever drawing API they like, so long as the API is available on the system and is supported by the browser.
| |
|
| |
|
| The bottom line: we want to make it very easy for developers to move their plugins from QuickDraw to CoreGraphics, while maintaining compatibility with QuickDraw-only browsers.
| | QuickDraw is default drawing model for 32-bit Mac OS X plugins. In 64-bit, the QuickDraw drawing model does not exist, Core Graphics is the default drawing model. The drawing model variables for Quickdraw are: |
|
| |
|
| == Excluding QuickDraw ==
| | * NPDrawingModelQuickDraw |
| | * NPNVsupportsQuickDrawBool |
|
| |
|
| Plugins and browsers that are compiled 64-bit must entirely exclude QuickDraw support, since there will be no 64-bit QuickDraw. | | Plugins and browsers that are compiled 64-bit must entirely exclude QuickDraw support, since there will be no 64-bit QuickDraw. |
| Line 35: |
Line 37: |
| You'll see this #define used throughout this proposal. | | You'll see this #define used throughout this proposal. |
|
| |
|
| == The Drawing Model == | | == The Core Graphics Drawing Model == |
| | |
| We're introducing the concept of the "drawing model" for Mac plugins. When the plugin starts, it negotiates a drawing model with the browser. The drawing model determines the type of graphics context created by the browser for the plugin.
| |
| | |
| A plugin may call NPN_GetValue() with the following NPNVariables to query the browser for its supported drawing models:
| |
| | |
| #ifndef NP_NO_QUICKDRAW
| |
| /* TRUE if the browser supports the QuickDraw drawing model */
| |
| NPNVsupportsQuickDrawBool = 2000
| |
| #endif
| |
| /* TRUE if the browser supports the CoreGraphics drawing model */
| |
| NPNVsupportsCoreGraphicsBool = 2001
| |
| | |
| Once the plugin finds a supported drawing model, it calls NPN_SetValue() to tell the browser which drawing model it will use. We're adding a new NPNVariable for this:
| |
| | |
| NPNVpluginDrawingModel = 1000 /* The NPDrawingModel specified by the plugin */
| |
| | |
| The value for the NPNVpluginDrawingModel is an NPDrawingModel, a new enumeration we're adding:
| |
| | |
| #ifdef XP_MACOSX<br>
| |
| /* The drawing model for a Mac OS X plugin. These are the possible values
| |
| * for the NPNVpluginDrawingModel variable.
| |
| */<br>
| |
| typedef enum {
| |
| #ifndef NP_NO_QUICKDRAW
| |
| NPDrawingModelQuickDraw = 0,
| |
| #endif
| |
| NPDrawingModelCoreGraphics = 1
| |
| } NPDrawingModel;<br>
| |
| #endif
| |
| | |
| If the browser does not support any of the plugin's drawing models, then the plugin should return an error from NPP_New() so that it is not started.
| |
| | |
| Here is an example of a CoreGraphics-only plugin negotiating the drawing model:
| |
| | |
| static NPError NPP_New(NPMIMEType pluginType, NPP instance,
| |
| uint16 mode, int16 argc, char* argn[],
| |
| char* argv[], NPSavedData* saved)
| |
| {
| |
| // Check if the browser supports the CoreGraphics drawing model
| |
| NPBool supportsCoreGraphics = FALSE;
| |
| NPError err = browser->getvalue(instance,
| |
| NPNVsupportsCoreGraphicsBool,
| |
| &supportsCoreGraphics);
| |
| if (err != NPERR_NO_ERROR || !supportsCoreGraphics)
| |
| return NPERR_INCOMPATIBLE_VERSION_ERROR;<br>
| |
| // Set the drawing model
| |
| err = browser->setvalue(instance,
| |
| NPNVpluginDrawingModel,
| |
| (void*)NPDrawingModelCoreGraphics);
| |
| if (err != NPERR_NO_ERROR)
| |
| return NPERR_INCOMPATIBLE_VERSION_ERROR;<br>
| |
| return NPERR_NO_ERROR;
| |
| }
| |
| | |
| == The QuickDraw drawing model ==
| |
| | |
| QuickDraw is the drawing model used by all plugins today. The [http://mydatapages.com/quickdraw.html QuickDraw] drawing model uses all the existing Mac NPAPI data structures and conventions. QuickDraw is the default drawing model, used when a plugin does not negotiate a drawing model. It is also used when the plugin explicitly sets the drawing model to NPDrawingModelQuickDraw.
| |
| | |
| In 64-bit, the QuickDraw drawing model does not exist, so CoreGraphics is the default drawing model.
| |
| | |
| == The CoreGraphics drawing model ==
| |
|
| |
|
| If a plugin sets the drawing model to NPDrawingModelCoreGraphics, then the meanings of some of the NPAPI data structures change: | | If a plugin sets the drawing model to NPDrawingModelCoreGraphics, then the meanings of some of the NPAPI data structures change: |
| Line 173: |
Line 114: |
|
| |
|
| This trick will not work once QuickDraw is removed from Mac OS X. It is intended for plugin developers that want to draw using CoreGraphics, yet remain compatible with QuickDraw-only browsers that haven't adopted these proposed NPAPI extensions. | | This trick will not work once QuickDraw is removed from Mac OS X. It is intended for plugin developers that want to draw using CoreGraphics, yet remain compatible with QuickDraw-only browsers that haven't adopted these proposed NPAPI extensions. |
|
| |
| == Your feedback is important! ==
| |
|
| |
| If you are at all involved in Mac browser or plugin development, these changes will affect you. So make your voice heard! We're open to any questions or comments you might have about these proposed changes. Please post comments on the plugin-futures (@mozilla.org) mailing list.
| |