XLua2 API Ref XPLMDataAccess Latest - 4.4.0-d4

Data Accessors

These routines read and write the data references. For each supported data type there is a reader and a writer.

If the dataref is orphaned, the plugin that provides it is disabled or there is a type mismatch, the functions that read data will return 0 as a default value or not modify the passed in memory. The plugins that write data will not write under these circumstances or if the dataref is read-only.

NOTE: to keep the overhead of reading datarefs low, these routines do not do full validation of a dataref; passing a junk value for a dataref can result in crashing the sim. The get/set APIs do check for NULL.

For array-style datarefs, you specify the number of items to read/write and the offset into the array; the actual number of items read or written is returned. This may be less the number requested to prevent an array-out-of-bounds error.

XPLMGetDatai

function

Read an integer dataref and return its value. The return value is the dataref value or 0 if the dataref is NULL or the plugin is disabled.

-- returns int -> assign to local/var
local my_result = XPLMGetDatai(
    inDataRef     -- XPLMDataRef
)

See associated types:

XPLMSetDatai

function

Write a new value to an integer dataref. This routine is a no-op if the plugin publishing the dataref is disabled, the dataref is NULL, or the dataref is not writable.

XPLMSetDatai(
    inDataRef,    -- XPLMDataRef
    inValue       -- int
)

See associated types:

XPLMGetDataf

function

Read a single precision floating point dataref and return its value. The return value is the dataref value or 0.0 if the dataref is NULL or the plugin is disabled.

-- returns float -> assign to local/var
local my_result = XPLMGetDataf(
    inDataRef     -- XPLMDataRef
)

See associated types:

XPLMSetDataf

function

Write a new value to a single precision floating point dataref. This routine is a no-op if the plugin publishing the dataref is disabled, the dataref is NULL, or the dataref is not writable.

XPLMSetDataf(
    inDataRef,    -- XPLMDataRef
    inValue       -- float
)

See associated types:

XPLMGetDatad

function

Read a double precision floating point dataref and return its value. The return value is the dataref value or 0.0 if the dataref is NULL or the plugin is disabled.

-- returns float -> assign to local/var
local my_result = XPLMGetDatad(
    inDataRef     -- XPLMDataRef
)

See associated types:

XPLMSetDatad

function

Write a new value to a double precision floating point dataref. This routine is a no-op if the plugin publishing the dataref is disabled, the dataref is NULL, or the dataref is not writable.

XPLMSetDatad(
    inDataRef,    -- XPLMDataRef
    inValue       -- float
)

See associated types:

XPLMGetDatavi

function

Read a part of an integer array dataref. If you pass NULL for outValues, the routine will return the size of the array, ignoring inOffset and inMax.

If outValues is not NULL, then up to inMax values are copied from the dataref into outValues, starting at inOffset in the dataref. If inMax + inOffset is larger than the size of the dataref, less than inMax values will be copied. The number of values copied is returned.

Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.

-- returns int -> assign to local/var
local my_result = XPLMGetDatavi(
    inDataRef,    -- XPLMDataRef
    outValues,    -- int
    inOffset,     -- ArrayOffset
    inMax         -- ArraySize
)

See associated types:

XPLMSetDatavi

function

Write part or all of an integer array dataref. The values passed by inValues are written into the dataref starting at inOffset. Up to inCount values are written; however if the values would write past the end of the dataref array, then fewer values are written.

Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.

XPLMSetDatavi(
    inDataRef,    -- XPLMDataRef
    inValues,     -- int
    inoffset,     -- ArrayOffset
    inCount       -- ArraySize
)

See associated types:

XPLMGetDatavf

function

Read a part of a single precision floating point array dataref. If you pass NULL for outValues, the routine will return the size of the array, ignoring inOffset and inMax.

If outValues is not NULL, then up to inMax values are copied from the dataref into outValues, starting at inOffset in the dataref. If inMax + inOffset is larger than the size of the dataref, less than inMax values will be copied. The number of values copied is returned.

Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.

-- returns int -> assign to local/var
local my_result = XPLMGetDatavf(
    inDataRef,    -- XPLMDataRef
    outValues,    -- float
    inOffset,     -- ArrayOffset
    inMax         -- ArraySize
)

See associated types:

XPLMSetDatavf

function

Write part or all of a single precision floating point array dataref. The values passed by inValues are written into the dataref starting at inOffset. Up to inCount values are written; however if the values would write past the end of the dataref array, then fewer values are written.

Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.

XPLMSetDatavf(
    inDataRef,    -- XPLMDataRef
    inValues,     -- float
    inoffset,     -- ArrayOffset
    inCount       -- ArraySize
)

See associated types:

XPLMGetDatab

function

Read a part of a byte array dataref. If you pass NULL for outValues, the routine will return the size of the array, ignoring inOffset and inMax.

If outValues is not NULL, then up to inMax values are copied from the dataref into outValues, starting at inOffset in the dataref. If inMax + inOffset is larger than the size of the dataref, less than inMax values will be copied. The number of values copied is returned.

Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.

-- returns int -> assign to local/var
local my_result = XPLMGetDatab(
    inDataRef,     -- XPLMDataRef
    outValue,      -- byte
    inOffset,      -- ArrayOffset
    inMaxBytes     -- ArraySize
)

See associated types:

XPLMSetDatab

function

Write part or all of a byte array dataref. The values passed by inValues are written into the dataref starting at inOffset. Up to inCount values are written; however if the values would write "off the end" of the dataref array, then fewer values are written.

Note: the semantics of array datarefs are entirely implemented by the plugin (or X-Plane) that provides the dataref, not the SDK itself; the above description is how these datarefs are intended to work, but a rogue plugin may have different behavior.

XPLMSetDatab(
    inDataRef,    -- XPLMDataRef
    inValue,      -- byte
    inOffset,     -- ArrayOffset
    inLength      -- ArraySize
)

See associated types: