Confirmed users
156
edits
mNo edit summary |
|||
(9 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
= Status = | = Status = | ||
Accepted, ready for implementation. | |||
= Contributors = | = Contributors = | ||
* Last modified: | * Last modified: April 19, 2012 | ||
* Authors: Bas Schouten (Mozilla Corporation), Josh Aas (Mozilla Corporation) | * Authors: Bas Schouten (Mozilla Corporation), Josh Aas (Mozilla Corporation) | ||
* Contributors: Robert O'Callahan (Mozilla Corporation) | * Contributors: Robert O'Callahan (Mozilla Corporation) | ||
Line 17: | Line 17: | ||
For documentation on negotiating drawing models, see [[NPAPI:Models]]. This specification covers all async models, which use the same drawing mechanics with platform-specific data structures. The following models are currently specified: | For documentation on negotiating drawing models, see [[NPAPI:Models]]. This specification covers all async models, which use the same drawing mechanics with platform-specific data structures. The following models are currently specified: | ||
* NPDrawingModelAsyncBitmapSurface (NPDrawingModel = | * NPDrawingModelAsyncBitmapSurface (NPDrawingModel = 7) | ||
* NPDrawingModelAsyncWindowsDXGISurface (NPDrawingModel = | * NPDrawingModelAsyncWindowsDXGISurface (NPDrawingModel = 8) | ||
Support query variables are: | Support query variables are: | ||
* NPNVsupportsAsyncBitmapSurfaceBool (NPNVariable = | * NPNVsupportsAsyncBitmapSurfaceBool (NPNVariable = 2007) | ||
* NPNVsupportsAsyncWindowsDXGISurfaceBool (NPNVariable = | * NPNVsupportsAsyncWindowsDXGISurfaceBool (NPNVariable = 2008) | ||
* | * NPNVpreferredDXGIAdapter (NPNVariable = 2009) | ||
Since these are the first new models for Windows and Linux the existing models will be assigned names: | Since these are the first new models for Windows and Linux the existing models will be assigned names: | ||
* NPDrawingModelSyncWin (NPDrawingModel = | * NPDrawingModelSyncWin (NPDrawingModel = 5) | ||
* NPDrawingModelSyncX (NPDrawingModel = | * NPDrawingModelSyncX (NPDrawingModel = 6) | ||
= General Async Drawing Mechanics = | = General Async Drawing Mechanics = | ||
Line 93: | Line 92: | ||
Surfaces cannot be modified while they are current. A modified rectangle may be provided in the <code>changed</code> argument to give the host a hint on which part of the surface was modified with respect to the previous current surface so that the browser can choose to optimize the composition process. There is no guarantee only this rectangle will be recomposed though and the entire surface needs to be valid. | Surfaces cannot be modified while they are current. A modified rectangle may be provided in the <code>changed</code> argument to give the host a hint on which part of the surface was modified with respect to the previous current surface so that the browser can choose to optimize the composition process. There is no guarantee only this rectangle will be recomposed though and the entire surface needs to be valid. | ||
SetCurrent can take NULL as | SetCurrent can take NULL as pthe surface. This removes the previous current surface. The plugin will render nothing. This should be used before finalizing the last surface. All three functions must be called on the plugin thread. | ||
Reentrant calls from the browser into the plugin do not occur during a SetCurrent invocation from the main thread. The browser is expected to implement SetCurrent using a locking protocol that cannot block for long. For example, SetCurrent might block only while the previous surface is being read by the browser's compositing. | |||
= Throttling Painting = | = Throttling Painting = | ||
Line 124: | Line 123: | ||
Plugins should finalize Windows shared surfaces by calling <code>NPN_FinalizeAsyncSurface</code> when they are done with the surface. | Plugins should finalize Windows shared surfaces by calling <code>NPN_FinalizeAsyncSurface</code> when they are done with the surface. | ||
== Creating the Device == | |||
On dual-GPU systems, the browser and plugin process may unintentionally bind to different GPUs if default DXGI parameters are used. When this happens the plugin's draw calls will most likely fail, or crash. To address this, it is necessary to open the browser's shared DXGI surfaces on the same adapter. The adapter can be found using <tt>NPNVpreferredDXGIAdapter</tt>. For example, | |||
<pre> | |||
static IDXGIAdapter1* | |||
FindDXGIAdapter(NPP npp, IDXGIFactory1* factory) | |||
{ | |||
DXGI_ADAPTER_DESC preferred; | |||
if (NPN_GetValue(npp, NPNVpreferredDXGIAdapter, &preferred) != NPERR_NO_ERROR) { | |||
return NULL; | |||
} | |||
for (UINT index = 0; ; index++) { | |||
IDXGIAdapter* adapter = NULL; | |||
if (FAILED(factory1->EnumAdapters1(index, &adapter)) || !adapter) { | |||
return nullptr; | |||
} | |||
DXGI_ADAPTER_DESC desc; | |||
if (SUCCEEDED(adapter->GetDesc(&desc)) && | |||
desc.AdapterLuid.LowPart == preferred.AdapterLuid.LowPart && | |||
desc.AdapterLuid.HighPart == preferred.AdapterLuid.HighPart) | |||
{ | |||
return adapter; | |||
} | |||
adapter->Release(); | |||
} | |||
return NULL; | |||
} | |||
</pre> | |||
The adapter returned by this function can then be used with any DXGI device creation function, such as <tt>D3D10CreateDevice</tt>. Failure to negotiate the adapter properly (or failure to use an IDXGIAdapter1) will result in undefined behavior. | |||
If no matching adapter can be found, the safest course of action for the plugin is to switch to a different drawing model (such the AsyncBitmap model). | |||
== Sample Code == | |||
This sample code illustrates usage of this drawing model: | This sample code illustrates usage of this drawing model: | ||
<pre> | |||
ID3D10Device *pDevice10; | ID3D10Device *pDevice10; | ||
NPAsyncSurface *npFrontBuffer = new NPAsyncSurface; | NPAsyncSurface *npFrontBuffer = new NPAsyncSurface; | ||
Line 156: | Line 194: | ||
backBuffer->QueryInterface(&mutex); | backBuffer->QueryInterface(&mutex); | ||
mutex->AcquireSync(0); | mutex->AcquireSync(0); | ||
... Draw to backBuffer texture ... | ... Draw to backBuffer texture ... | ||
mutex->ReleaseSync(0); | mutex->ReleaseSync(0); | ||
mutex->Release(); | mutex->Release(); | ||
Line 186: | Line 224: | ||
delete npBackBuffer; | delete npBackBuffer; | ||
} | } | ||
</pre> | |||