137 lines
5.1 KiB
C
137 lines
5.1 KiB
C
#ifndef _XPLMInstance_h_
|
|
#define _XPLMInstance_h_
|
|
|
|
/*
|
|
* Copyright 2005-2012 Sandy Barbour and Ben Supnik All rights reserved. See
|
|
* license.txt for usage. X-Plane SDK Version: 2.1.1
|
|
*
|
|
*/
|
|
|
|
/***************************************************************************
|
|
* XPLMInstance
|
|
***************************************************************************/
|
|
/*
|
|
* 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.)
|
|
*
|
|
*/
|
|
|
|
#include "XPLMDefs.h"
|
|
#include "XPLMScenery.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/***************************************************************************
|
|
* Instance Creation and Destruction
|
|
***************************************************************************/
|
|
/*
|
|
* Registers and unregisters instances.
|
|
*
|
|
*/
|
|
|
|
|
|
/*
|
|
* XPLMInstanceRef
|
|
*
|
|
* An opaque handle to an instance.
|
|
*
|
|
*/
|
|
typedef void * 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.
|
|
*
|
|
*/
|
|
XPLM_API XPLMInstanceRef XPLMCreateInstance(
|
|
XPLMObjectRef obj,
|
|
const char ** datarefs);
|
|
|
|
/*
|
|
* 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.
|
|
*
|
|
*/
|
|
XPLM_API void XPLMDestroyInstance(
|
|
XPLMInstanceRef instance);
|
|
|
|
/***************************************************************************
|
|
* 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.
|
|
*
|
|
*/
|
|
XPLM_API void XPLMInstanceSetPosition(
|
|
XPLMInstanceRef instance,
|
|
const XPLMDrawInfo_t * new_position,
|
|
const float * data);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|