XLua2 API Ref XPLMCamera Latest - 4.4.0-d4

Camera Control

XPLMCameraControlDuration

enum

This enumeration states how long you want to retain control of the camera. You can retain it indefinitely or until the user selects a new view.

Name Value Description
xplm_ControlCameraUntilViewChanges 1 Control the camera until the user picks a new view.
xplm_ControlCameraForever 2 Control the camera until your plugin is disabled or another plugin forcibly takes control.

Used by:

XPLMCameraPosition_t

struct

This structure contains a full specification of the camera. X, Y, and Z are the camera's position in OpenGL coordinates; pitch, roll, and yaw are rotations from a camera facing flat north in degrees. Positive pitch means nose up, positive roll means roll right, and positive yaw means yaw right, all in degrees. Zoom is a zoom factor, with 1.0 meaning normal zoom and 2.0 magnifying by 2x (objects appear larger).

local My_CameraPosition_t = {
    x        = 0.0,     -- float
    y        = 0.0,     -- float
    z        = 0.0,     -- float
    pitch    = 0.0,     -- float
    heading  = 0.0,     -- float
    roll     = 0.0,     -- float
    zoom     = 0.0,     -- float
}

XPLMCameraControl_f

callback

You use an XPLMCameraControl function to provide continuous control over the camera. You are passed a structure in which to put the new camera position; modify it and return true to reposition the camera. Return false to surrender control of the camera; camera control will be handled by X-Plane on this draw loop. The contents of the structure as you are called are undefined.

If X-Plane is taking camera control away from you, this function will be called with inIsLosingControl set to true and ioCameraPosition NULL.

function my_CameraControl_callback(
    outCameraPosition,    -- see XPLMCameraPosition_t
    inIsLosingControl,    -- boolean
    inRefcon              -- any Lua var/table
)
    -- your code here
    return true  -- boolean
end

See associated types:

XPLMControlCamera

function

This function repositions the camera on the next drawing cycle. You must pass a non-null control function. Specify in inHowLong how long you'd like control (indefinitely or until a new view mode is set by the user).

XPLMControlCamera(
    inHowLong,        -- XPLMCameraControlDuration
    inControlFunc,    -- see XPLMCameraControl_f
    inRefcon          -- any Lua var/table
)

See associated types:

XPLMDontControlCamera

function

This function stops you from controlling the camera. If you have a camera control function, it will not be called with an inIsLosingControl flag. X-Plane will control the camera on the next cycle.

For maximum compatibility you should not use this routine unless you are in posession of the camera.

XPLMDontControlCamera(
)

XPLMIsCameraBeingControlled

function

This routine returns true if the camera is being controlled, false if it is not. If it is and you pass in a pointer to a camera control duration, the current control duration will be returned.

-- returns boolean -> assign to local/var
local my_result = XPLMIsCameraBeingControlled(
    outCameraControlDuration     -- XPLMCameraControlDuration
)

See associated types:

XPLMReadCameraPosition

function

This function reads the current camera position.

XPLMReadCameraPosition(
    outCameraPosition     -- see XPLMCameraPosition_t
)

See associated types: