CAMERA API

IMPORTANT! This API is currently in beta and may be subject to change.The Camera API is used for manipulating and controlling the camera using WebAssembly. There is also a corresponding API for SimConnect, which you can find here:

• SimConnect Camera API

 

The camera these functions access is a unique camera instance that exists only to be used by add-ons, and it can be acquired using the functions listed below. Camera acquisition is based on a queue, which means that if a client A has acquired the camera, another client B can later "steal" the camera, in which case client A will receive a message informing them that another client possesses the camera. Once client B releases the camera, it will be given back to client A, unless that client has also released it.

 

It is important to note that just because a client has acquired the camera, it does not mean that the client as all rights on the simulation's cameras and the following circumstances can revoke that control, either temporarily or permanently:

• The simulation can temporarily take back control of the cameras during specific parts of the flow (during menu interactions, when the simulation is paused, during RTC's etc…). Outside of these specific situations, control of cameras will be given back to the add-on which had acquired the dedicated camera previously.
• The user has all rights over the cameras. Through the simulation camera UI panel, the user can revoke the acquisition of the add-on camera and/or forbid its future acquisition.

Under either of the above circumstances, appropriate information will be sent to all clients which have subscribed to the camera event, even if they haven't acquired the camera, so that measures can be taken.

 

 

World Lockers

The camera API also permits the placement of a world locker to "lock" the world at a location before the camera is moved there. This locker will essentially "lock" the scenery and SimObjects at the location in memory so the user doesn't experience loading issues and "popping" when the camera moves to the location. It is important to note the following caveats:

• A world locker cannot be placed in the world unless the camera has first been acquired by the add-on.
• Lockers are very resource intensive and should only be used sparingly, and they should be removed the moment they are no longer required.

 

 

Functions

The following functions are available for the Camera API:

 

Function	Description
fsCameraAcquire	Used to acquire the add-on camera, if possible.
fsCameraDeleteCameraWorldLocker	Used to delete a locker previously set in the world
fsCameraDisableFlag	Used to disable camera specific features, but only if the camera has been correctly acquired.
fsCameraEnableFlag	Used to enable camera specific features, but only if the camera has been correctly acquired.
fsCameraEnumerateCameraDefinitions	Used to retrieve an array of all the defined camera names.
fsCameraGet	Used to get the add-on camera settings, regardless of whether it has been acquired or not.
fsCameraGetStatus	Used to get the add-on camera status.
fsCameraRelease	Release a previously acquired camera when no longer required or for other systems to acquire it.
fsCameraRequestCameraWorldLocker	Used to set a locker to load the world around it.
fsCameraSet	Used to set the add-on camera settings, if it has been correctly acquired.
fsCameraSetUsingCameraDefinition	Used to set the add-on camera settings using parameters taken from a predefined camera.
fsCameraSubscribeToCameraWorldLockerStatusUpdate	Used to subscribe to camera world locker status update messages.
fsCameraSubscribeToStatusUpdate	Used to subscribe to camera status update messages.
fsCameraUnsubscribeToCameraWorldLockerStatusUpdate	Used to unsubscribe from camera world locker update messages.
fsCameraUnsubscribeToStatusUpdate	Used to unsubscribe from camera update messages.

 

 

Enums/Structs

The enums and structs available for use with the Camera API are:

 

Function	Description	Type
FsAcquiredState	An enum used for the add-on camera acquired status in functions like fsCameraGetStatus.	Enum
FsCameraData	A struct returned by functions like fsCameraGet which contains data on the current camera.	Struct
FsCameraDataMask	An enum used to create a bitmask for use with the fsCameraSet function.	Enum
FsCameraEvent	An enum returned as part of the fsCameraStatusUpdateCallback callback defining what kind of event triggered the callback.	Enum
FsCameraFlag	An enum used by the fsCameraEnableFlag and fsCameraDisableFlag functions to get/set flags in a bitmask for the add-on camera options.	Enum
FsCameraWorldLockerStatus	An enum used by fsCameraSubscribeToStatusUpdate to describe the different possible camera world locker status.	Enum
FsPositionReferential	Enum of values used to define the referential to use for the camera position values in the FsCameraData struct.	Enum

 

 

Typedefs

When using the functions listed above, you'll need to also have the following type definitions, as they will be used as return values or to create callbacks by many of the functions. These typedefs are listed below.

 

 

fsCameraStatusUpdateCallback

The callback invoked when fsCameraSubscribeToStatusUpdate receives a message from the simulation that the camera status has changed:

typedef void (*fsCameraStatusUpdateCallback)(
    FsCameraEvent event,
    const FsAcquiredState acquiredState,
    const bool gameControlled,
    void* ctx
    );

Parameters	Description
event	What kind of event has generated the callback. Will be one of the FsCameraEvent enum members.
acquiredState	Contains one of the members of the FsAcquiredState enum to indicate what status the add-on camera has.
gameControlled	Will be true if the camera is currently controlled by the simulation, or false otherwise (regardless of the camera status).
ctx	The context of the call that generated the callback.

 

 

fsCameraWorldLockerStatusUpdateCallback

The callback invoked when fsCameraSubscribeToCameraWorldLockerStatusUpdate receives a message from the simulation that the camera status has changed:

typedef void (*fsCameraSubscribeToCameraWorldLockerStatusUpdate)(
    FsCameraWorldLockerStatus status,
    void* ctx
    );

Parameters	Description
status	Contains one of the members of the FsCameraWorldLockerStatus enum to indicate what status the camera locker has.
ctx	The context of the call that generated the callback.

 

Report An Issue