126 lines
5.1 KiB
ObjectPascal
126 lines
5.1 KiB
ObjectPascal
{
|
|
Copyright 2005-2012 Sandy Barbour and Ben Supnik All rights reserved. See
|
|
license.txt for usage. X-Plane SDK Version: 2.1.1
|
|
}
|
|
|
|
UNIT XPLMInstance;
|
|
INTERFACE
|
|
{
|
|
This API provides instanced drawing of X-Plane objects (.obj files). In
|
|
contrast to old drawing APIs, which required you to draw your own objects
|
|
per-frame, the instancing API allows you to simply register an OBJ for
|
|
drawing, then move or manipulate it later (as needed).
|
|
|
|
This provides one tremendous benefit: it keeps all dataref operations for
|
|
your object in one place. Because datarefs are main thread only, allowing
|
|
dataref access anywhere is a serious performance bottleneck for the
|
|
simulator---the whole simulator has to pause and wait for each dataref
|
|
access. This performance penalty will only grow worse as X-Plane moves
|
|
toward an ever more heavily multithreaded engine.
|
|
|
|
The instancing API allows X-Plane to isolate all dataref manipulations for
|
|
all plugin object drawing to one place, potentially providing huge
|
|
performance gains.
|
|
|
|
Here's how it works:
|
|
|
|
When an instance is created, it provides a list of all datarefs you want to
|
|
manipulate in for the OBJ in the future. This list of datarefs replaces the
|
|
ad-hoc collections of dataref objects previously used by art assets. Then,
|
|
per-frame, you can manipulate the instance by passing in a "block" of
|
|
packed floats representing the current values of the datarefs for your
|
|
instance. (Note that the ordering of this set of packed floats must exactly
|
|
match the ordering of the datarefs when you created your instance.)
|
|
}
|
|
|
|
USES
|
|
XPLMDefs, XPLMScenery;
|
|
{$A4}
|
|
{___________________________________________________________________________
|
|
* Instance Creation and Destruction
|
|
___________________________________________________________________________}
|
|
{
|
|
Registers and unregisters instances.
|
|
}
|
|
|
|
|
|
TYPE
|
|
{
|
|
XPLMInstanceRef
|
|
|
|
An opaque handle to an instance.
|
|
}
|
|
XPLMInstanceRef = pointer;
|
|
PXPLMInstanceRef = ^XPLMInstanceRef;
|
|
|
|
{
|
|
XPLMCreateInstance
|
|
|
|
XPLMCreateInstance creates a new instance, managed by your plug-in, and
|
|
returns a handle to the instance. A few important requirements:
|
|
|
|
* The object passed in must be fully loaded and returned from the XPLM
|
|
before you can create your instance; you cannot pass a null obj ref, nor
|
|
can you change the ref later.
|
|
|
|
* If you use any custom datarefs in your object, they must be registered
|
|
before the object is loaded. This is true even if their data will be
|
|
provided via the instance dataref list.
|
|
|
|
* The instance dataref array must be a valid ptr to an array of at least
|
|
one item that is null terminated. That is, if you do not want any
|
|
datarefs, you must passa ptr to an array with a null item. You cannot
|
|
pass null for this.
|
|
}
|
|
FUNCTION XPLMCreateInstance(
|
|
obj : XPLMObjectRef;
|
|
datarefs : PXPLMString) : XPLMInstanceRef;
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMDestroyInstance
|
|
|
|
XPLMDestroyInstance destroys and deallocates your instance; once called,
|
|
you are still responsible for releasing the OBJ ref.
|
|
|
|
Tip: you can release your OBJ ref after you call XPLMCreateInstance as long
|
|
as you never use it again; the instance will maintain its own reference to
|
|
the OBJ and the object OBJ be deallocated when the instance is destroyed.
|
|
}
|
|
PROCEDURE XPLMDestroyInstance(
|
|
instance : XPLMInstanceRef);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{___________________________________________________________________________
|
|
* Instance Manipulation
|
|
___________________________________________________________________________}
|
|
|
|
{
|
|
XPLMInstanceSetPosition
|
|
|
|
Updates both the position of the instance and all datarefs you registered
|
|
for it. Call this from a flight loop callback or UI callback.
|
|
|
|
__DO NOT__ call XPLMInstanceSetPosition from a drawing callback; the whole
|
|
point of instancing is that you do not need any drawing callbacks. Setting
|
|
instance data from a drawing callback may have undefined consequences, and
|
|
the drawing callback hurts FPS unnecessarily.
|
|
|
|
The memory pointed to by the data pointer must be large enough to hold one
|
|
float for every data ref you have registered, and must contain valid
|
|
floating point data.
|
|
|
|
BUG: before X-Plane 11.50, if you have no dataref registered, you must
|
|
still pass a valid pointer for data and not null.
|
|
}
|
|
PROCEDURE XPLMInstanceSetPosition(
|
|
instance : XPLMInstanceRef;
|
|
new_position : PXPLMDrawInfo_t;
|
|
data : PSingle);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
|
|
IMPLEMENTATION
|
|
|
|
END.
|