Rendering PDK Overview

Contents

Overview
IWindowPluginSystem
IWindowPlugin
IWindowPdk
IWindowReaderPdk
IWindowCallback
ICustomInputCallback
IMouseRectListenerCallback
IPluginSystem
ITextureRenderPlugin
IEffectsRenderPlugin
ICustomRenderCallback
IRenderData

Overview

The Rendering PDK enables external applications to control basic camera functions as well as adding/removing post-process effects and sensor modes using camera plug-ins. It also allows for custom DirectX® 11 rendering into textures or overlayed onto a view using custom texture and effect plug-ins. This is split up into two main sections, the Camera PDK and the Texture and Effects PDK.

Refer to the Camera PDK, Texture and Effect Render Plug-in Gauge Sample, and Camera Picking Sample sections for specific examples on how to use the Rendering PDK.

IWindowPluginSystem

Plug-in system used for creating window plug-ins and registering system callbacks.

GetOrCreatePlugin

HRESULT GetOrCreatePlugin	(	REFIID	id,
		void **	plugin
	)

Get or create plug-in

Parameters

	id	Interface ID
[out]	pointer	to hold plug-in that is created or retrieved

RegisterFlightLoaded

HRESULT RegisterFlightLoaded	(	IWindowCallback *	callback
	)

Parameters

[in] callback Callback to register

RegisterHmdViewOpened

HRESULT RegisterHmdViewOpened	(	IWindowCallback *	callback
	)

Parameters

[in] callback Callback to register

RegisterHmdViewClosed

HRESULT RegisterHmdViewClosed	(	IWindowCallback *	callback
	)

Parameters

[in] callback Callback to register

HmdConnected

HRESULT HmdConnected	(	UINT	type
	)

Notify system HMD has been connected.

Parameters

[in] type The HMD type (0 = none, 1 = Oculus)

HmdDisconnected

HRESULT HmdDisconnected	(	UINT	type
	)

Notify system HMD has been disconnected.

Parameters

[in] type The HMD type (0 = none, 1 = Oculus)

RegisterMouseRectListenerCallback

HRESULT RegisterMouseRectListenerCallback	(	IMouseRectListenerCallback*	callback
	)

Parameters

callback Callback interface to register.

UnRegisterMouseRectListenerCallback

HRESULT RegisterMouseRectListenerCallback	(	IMouseRectListenerCallback*	callback
	)

Unregister an IMouseRectListenerCallback with the IWindowPluginSystem.

Parameters

[in] callback Callback interface to unregister.

FireMouseRectClick

HRESULT FireMouseRectClick	(	UINT	id,
		MOUSE_CLICK_TYPE	clickType
	)

Emulates the given click type on the given mouse rectangle id.

Parameters

[in]	id	The id of the mouse rectangle.
[in]	clickType	The click type to emulate.

UnRegisterFlightLoaded

HRESULT UnRegisterFlightLoaded	(	IWindowCallback*	callback
	)

UnRegister a callback to be hit when a flight file or mission is loaded

Parameters

[in] callback Callback to unregister

UnRegisterHmdViewOpened

HRESULT UnRegisterHmdViewOpened	(	IWindowCallback*	callback
	)

UnRegister a callback to be hit when an HMD view is opened

Parameters

[in] callback Callback to unregister

UnRegisterHmdViewClosed

HRESULT UnRegisterHmdViewClosed	(	IWindowCallback*	callback
	)

UnRegister a callback to be hit when an HMD view is closed

Parameters

[in] callback Callback to unregister

IWindowPlugin

Plug-in interface to the Prepar3D window manager which allows plug-ins to manage windows.

HasWindow

BOOL HasWindow ( const char * name )

Check if a window containing a 3d view exists

Parameters

[in] name Name of the window

Returns: true if window exists, false if not

GetWindowSize

UINT GetWindowSize ( void )

Get the current number windows which contain a 3D view.

Returns: The current number windows which contain a 3D view

GetWindowList

HRESULT GetWindowList	(	IWindowReaderPdk **	list,
		UINT &	size
	)

Get list of windows containing a 3D view that are currently open

Parameters

[out]	list	list of IWindowReaderPdk interfaces
[out]	size	number of windows in the list

Returns: HRESULT, S_OK if function succeeds

GetWindow

HRESULT GetWindow	(	const char *	name,
		IWindowReaderPdk *&	window
	)

Get a IWindowReaderPdk interface for a 3D view window with the input name

Parameters

[in]	name	Name of the window
[out]	window	IWindowReaderPdk interface for getting window state information

Returns: HRESULT, S_OK if function succeeds

RegisterInternalWindow

HRESULT RegisterInternalWindow	(	const char *	name,
		IWindowCallback *	callback
	)

Parameters

[in]	name	Name of the window
[in]	callback	IWindowCallback that will be registered to the window

Returns: HRESULT, S_OK if function succeeds

Remarks: the callback will be called each frame the window is used until it is unregistered

UnRegisterInternalWindow

HRESULT UnRegisterInternalWindow	(	const char *	name,
		IWindowCallback *	callback
	)

Unregister a callback from an existing window. Return error if window does not exist

Parameters

[in]	name	Name of the window
[in]	callback	IWindowCallback that will be unregistered

Returns: HRESULT, S_OK if function succeeds

CreateInternalWindow

HRESULT CreateInternalWindow	(	const char *	name,
		UINT32	x,
		UINT32	y,
		UINT32	width,
		UINT32	height,
		IWindowCallback *	windowCallback
		ICustomInputCallback *	inputCallback
		bool *	isRTT
	)

Create a new window and register a callback. Return error if window already exist

Parameters

[in]	name	Name of the window
[in]	x,y	Window position relative to parent window. (origin is top left corner)
[in]	width,height	Window dimensions in pixels
[in]	windowCallback	IWindowCallback to be registered at creation time
[in]	inputCallback	ICustomInputCallback to be registered at creation time
[in]	isRTT	set true to override camera definition value and create a window as a Render-To-Texture view

Returns: HRESULT, S_OK if function succeeds

CloseInternalWindow

HRESULT CloseInternalWindow ( const char * name )

Close an existing window Return error if window does not exist

Parameters

[in] name Name of the window

Returns: HRESULT, S_OK if function succeeds

GetWindowWriterList

HRESULT GetWindowWriterList	(	IWindowPdk**	list,
		UINT &	size
)

Get list of windows containing a 3D view that are currently open

Parameters

[out]	list	list of IWindowPdk interfaces
[out]	size	number of windows in the list

Returns: HRESULT, S_OK if function succeeds

GetWindowWriter

HRESULT GetWindowWriter	(	const char*	name,
		IWindowPdk*	window
)

Get a IWindowPdk interface for a 3D view window with the passed in name

Parameters

[in]	name	Name of the window
[out]	window	IWindowPdk interface for setting window state information

Returns: HRESULT, S_OK if function succeeds

IWindowPdk

Window writer interface for setting window state values from inside a window plug-in callback

SetCameraDefinition

void SetCameraDefinition ( const char * name )

Set the window to use the specified camera definition

Parameters

name	Name of camera definition

Remarks: camera definitions are defined in Cameras.cfg or in aircraft.cfg

SetDocking

void SetDocking ( BOOL isDocked )

Set Docked/Undocked state

Parameters

isDocked Set TRUE to dock or FALSE to undock a window

SetPosition

void SetPosition	(	UINT32	x,
		UINT32	y
	)

Set the position of the window in screen space

Parameters

x,y	Screen-space position of window

SetSize

void SetSize	(	UINT32	,
		UINT32
	)

Set the size of a window in pixels

Parameters

width,height Window size in pixels

SetRelative6DOF

void SetRelative6DOF	(	float	fDeltaX,
		float	fDeltaY,
		float	fDeltaZ,
		float	fPitchDeg,
		float	fBankDeg,
		float	fHeadingDeg
	)

Set the camera position and orientation relative to its origin in 3D space

Parameters

fDeltaX,fDeltaY,fDeltaZ	3D position relative to origin
fPitchDeg,fBankDeg,fHeadingDeg	Relative orientation pitch bank and heading

SetSmoothRelative6DOF

void SetSmoothRelative6DOF	(	float	fDeltaX,
		float	fDeltaY,
		float	fDeltaZ,
		float	fPitchDeg,
		float	fBankDeg,
		float	fHeadingDeg,
		float	smoothPanTime
	)

Change the relative position and orientation of camera using a smooth transition

Parameters

fDeltaX,fDeltaY,fDeltaZ	3D position relative to origin
fPitchDeg,fBankDeg,fHeadingDeg	Relative orientation pitch bank and heading
smoothPanTime	Time frame for the camera to pan to the new position

SetFov

void SetFov	(	float	hFov,
		float	vFov
	)

Set the field of view of the camera

Parameters

hFov	Horizontal field of view
vFov	Vertical field of view

SetZoomGoal

void SetZoomGoal ( float zoomGoal )

Set the Zoom goal for the camera

Parameters

zoomGoal Zoom goal to set

SetZoom

void SetZoom ( float zoom )

Set the Zoom

Parameters

zoom

PanToView

void PanToView ( const char * name )

Pan the camera to a saved location

Parameters

name	of saved custom camera to pan to

AddPostProcess

void AddPostProcess ( const char * name )

Add a post process effect to the window

Parameters

name	Name of post process to add

RemovePostProcess

void RemovePostProcess ( const char * name )

Remove a post process effect to the window

Parameters

name	Name of post process to remove

ResetPostProcess

void ResetPostProcess ( )

Reset all post process effects to those defined in camera definition

ClearPostProcess

void ClearPostProcess ( )

Clear all post process effects from the camera

ZoomIn

void ZoomIn ( void )

Zoom in one zoom level increment

ZoomOut

void ZoomOut ( void )

Zoom out one zoom level increment

SetVirtualCockpitTransparentValue

void SetVirtualCockpitTransparentValue ( unsigned int level )

Sets a cockpit transparency level

Parameters

level value between [0-100] to indicate the transparent level. 100 is Fully transparent.

SetChaseDistance

void SetChaseDistance ( float fDistance )

Sets the chase distance of a camera

Parameters

fDistance Chase distance in meters

Note: This only works for cameras that follow the airplane.

SetSensorMode

void SetSensorMode ( unsigned int mode )

Sets the sensor mode of a camera

Parameters

mode	Sensor mode (0: None, 1: IR White Hot, 2: IR Black Hot, 3: GData

SetExcludeVcPostProcess

void SetExcludeVcPostProcess ( bool exclude )

Excludes entire VC from being post processed (if post process has PreVC enabled)

Parameters

exclude boolean value to set exclusion state

SetExcludeVcPanelsSensor

void SetExcludeVcPanelsSensor ( bool exclude )

Excludes VC panels from being sensorized

Parameters

exclude boolean value to set exclusion state

SetFarClip

void SetFarClip ( float far )

Set the far clip.

Parameters

far	Far clip distance in meters

SetNearClip

void SetNearClip ( float near )

Set the near clip.

Parameters

near	Near clip distance in meters

SetPanelOnly

void SetPanelOnly ( bool isPanelOnly )

Set panel-only state. Enabling panel-only will black out the window and prevent it from rendering.

Parameters

isPanelOnly boolean value to set panel-only state

SetCameraLODOriginLLA

void SetCameraLODOriginLLA	(	double	lat,
		double	lon
		double	alt
	)

Set the origin of the scenery load point. This causes the center of the scenery LOD be set to the LLA passed in this call. This must be set every frame, or it will revert to the LLA of the camera.

Parameters

lat	latitude of scenery origin
lon	longitude of scenery origin
alt	altitude of scenery origin

SetAmbientBoostAndLightAmplificationLevel

void SetAmbientBoostAndLightAmplificationLevel	(	float	ambientBoost,
		float	lightAmplificationLevel
	)

Set ambient boost and light amplification values for a camera. This can be useful for representing high exposure cameras or night vision goggles.

Parameters

ambientBoost	value to add to ambient component of all lights in a scene. This will brighten the scene even when no direct light is present and is useful for representing night vision.
lightAmplificationLevel	Multiplier applied to diffuse light. This can be used to brighten or darken the scene. By increasing or decreasing the brightness of light sources.

AddPickRequest

int AddPickRequest	(	int	x,
		int	y
	)

Request a Pick test at a given screen coordinate. An ID is returned which can later be used to request the results of the test. The result provides the distance to the intersection, which can be useful for things such as supporting virtual hands in the cockpit in a virtual reality plugin.

Parameters

x	Horizontal screen coordinate in pixels relative to the window's top left corner.
y	Vertical screen coordinate in pixels relative to the window's top left corner.

Returns: int, ID of pick request which must be used later to get the result using GetPickResult.

ActivatePositionTracking

void ActivatePositionTracking ( )

Activates camera position tracking. The camera's view will be locked to the LLA specified in the SetTargetLatLonAltDegrees function.

DeactivatePositionTracking

void DeactivatePositionTracking ( )

Deactivates camera position tracking.

ActivateEntityTracking

void ActivateEntityTracking ( )

Activates camera entity tracking. The camera's view will be locked to the position of the entity specified in the SetTargetContainerId function.

DeactivateEntityTracking

void DeactivateEntityTracking ( )

Deactivates camera entity tracking.

SetTargetLatLonAltDegrees

void SetTargetLatLonAltDegrees	(	double	lat,
		double	lon,
		double	alt
	)

Sets the target location for the camera to track when position tracking is enabled.

Parameters

lat	The target latitude in degrees.
lon	The target longitude in degrees.
alt	The target altitude in meters.

SetTargetContainerId

void SetTargetContainerId ( unsigned int containerId )

Sets the target entity for the camera to track when entity tracking is enabled.

Parameters

containerId The container ID of the object to track.

SetPBH

void SetPBH	(	float	pitch,
		float	bank,
		float	heading
	)

Sets the camera's PBH in degrees.

Parameters

pitch	Pitch in degrees.
bank	Bank in degrees.
heading	Heading in meters.

SetOffsetXYZ

void SetOffsetXYZ	(	float	x,
		float	y,
		float	z
	)

Sets the camera's offset in meters.

Parameters

x	X offset in meters.
y	Y offset in meters.
z	Z offset in meters.

SetFrustumOffsetXYZ

void SetFrustumOffsetXYZ	(	float	fOffsetX,
		float	fOffsetY,
		float	fOffsetZ
	)

Sets the camera's offset from the origin of a camera group.

Parameters

fOffsetX	X offset in meters.
fOffsetY	Y offset in meters.
fOffsetZ	Z offset in meters.

SetFrustumOffsetPBH

void SetFrustumOffsetPBH	(	float	fOffsetP,
		float	fOffsetB,
		float	fOffsetH
	)

Sets the camera's rotation offset from the origin of a camera group.

Parameters

fOffsetP	Pitch offset in degrees.
fOffsetB	Bank offset in degrees.
fOffsetH	Heading offset in degrees.

SetGlobalRotate

void SetGlobalRotate ( bool globalRotate )

Sets the camera to rotate independent of the user vehicle. All rotation will be made relative to the world instead of relative to the vehicle. Current PBH of the vehicle will not be applied to the camera in this case and all PBH setting must be done using the SetGlobalPBH function

Parameters

globalRotate Whether or not the camera will rotate relative to the world instead of vehicle.

SetGlobalPBH

void SetGlobalPBH	(	float	pitch,
		float	bank,
		float	heading
	)

Sets the camera's global PBH in degrees. This is used when the camera is in global rotation mode enabled by the SetGlobalRotate function

Parameters

pitch	Pitch in degrees.
bank	Bank in degrees.
heading	Heading in meters.

TargetCameraLookAt

void TargetCameraLookAt ( )

Automatically sets the camera to target ground at center of view

IWindowReaderPdk

Window reader interface for getting window state information

IsDocked

bool IsDocked ( ) const

Get window's docking state

Returns: bool value of true if window is docked and false if not

GetPosition

void GetPosition	(	UINT32 &	topLeftX,
		UINT32 &	topLeftY
	)		const

Get the position of the window in screen space

Parameters

[out] topLeftX,topLeftY position of the window in screen space

GetSize

void GetSize	(	UINT32 &	width,
		UINT32 &	height
	)		const

Get the size of the window in screen space

Parameters

[out] width,height size of the window in screen space

GetFov

void GetFov	(	float &	hFov,
		float &	vFov
	)		const

Get the field of view of the camera

Parameters

[out]	hFov	Horizontal field of view
[out]	vFov	Vertical field of view

GetZoom

void GetZoom ( float & fZoom ) const

Get the Zoom

Parameters

[out] fZoom zoom value

GetPBH

void GetPBH	(	float &	p,
		float &	b,
		float &	h
	)		const

Get the orientation of the camera (Pitch, Bank, and Heading)

Parameters

[out]	p	Pitch
[out]	b	Bank
[out]	h	Heading

GetBiasPBH

void GetBiasPBH	(	float &	p,
		float &	b,
		float &	h
	)		const

Get the offset of the pbh relative to the origin

Parameters

[out]	p	Pitch
[out]	b	Bank
[out]	h	Heading

GetLLA

void GetLLA	(	double &	lat,
		double &	lon,
		double &	alt
	)		const

Get the offset of the latitude longitude and altitude of the camera

Parameters

[out]	lat	Latitude
[out]	lon	Longitude
[out]	alt	Altitude

GetCameraOffset

void GetCameraOffset	(	float &	x,
		float &	y,
		float &	z
	)		const

Get the camera offset from the origin

Parameters

[out] x,y,z camera's 3d offset from origin

GetWindowName

const char* GetWindowName ( void ) const

Get the window name

Returns: window name

IsVirtualCockpit

bool IsVirtualCockpit ( void ) const

Check if camera is a virtual cockpit

Returns: true if window's active camera is a virtual cockpit view

IsActiveWindow

bool IsActiveWindow ( void ) const

Check if window's active camera is in focus

Returns: true if window's active camera is in focus

GetScreenCoord

void GetScreenCoord	(	const double	lla[3],
		const float	pbh[3],
		const float	xyzOffset[][3],
		float	xyOutput[][3],
		const int	count
	)		const

Get the screen coord of a point LLA + xyz offset in world space (meters)

Parameters

[in]	lla	Lat lon alt origin of local coordinate system
[in]	pbh	Orientation of local coordinate system
[in]	xyzOffset	List of 3d offsets in local coordinates.
[out]	xyOutput	List of screenspace position of the requested points
[in]	count	Number of points to request. Must be at least as big as input array sizes.

GetScreenCoord

void GetScreenCoord	(	const float	xyzOffset[][3],
		float	xyOutput[][3],
		const int	count
	)		const

Get the screen space coordinates of a list of points relative to user sim object

Parameters

[in]	xyzOffset	list of 3d offsets in local coordinates.
[out]	xyOutput	list of screenspace position of the requested points
[in]	count	Number of points to request. Must be at least as big as input array sizes.

GetVirtualCockpitTransparentValue

unsigned int GetVirtualCockpitTransparentValue ( ) const

Get transparency level

Returns: value between [0-100] to indicate the transparency level. 100 is fully transparent

GetChaseDistance

float GetChaseDistance ( ) const

Gets the chase distance in meters

Returns: Chase distance in meters

Note: This only works for cameras that follow the airplane.

IsMainAppWindow

bool IsMainAppWindow ( ) const

Is this the main application window?

Returns: bool, true if window is Prepar3D's main app window.

GetPostProcesses

void GetPostProcesses	(	char **	nameList,
		int &	size
	)		const

Gets list of the names of post processes assigned to this window

Parameters

[out]	nameList	array of cstrings to hold the list of names (size should be 32)
[out]	size	of list returned (will not be larger than 32)

GetViewMatrix

void GetViewMatrix	(	[out]	float[4][4]	output4x4,
	)		const

Get View Matrix for this Camera/Window

Parameters

[out] output4x4 4x4 view matrix

GetStandardProjectionMatrix

void GetStandardProjectionMatrix	(	[out]	float[4][4]	output4x4
	)		const

Get the standard projection matrix which is used by the Camera/Window for rendering everything but the virtual cockpit.

Parameters

[out] output4x4 4x4 projection matrix

GetVirtualCockpitProjectionMatrix

void GetVirtualCockpitProjectionMatrix	(	[out]	float[4][4]	output4x4
	)		const

Get the projection matrix which is used by the Camera/Window for rendering the virtual cockpit. The VC projection has a different near and far clip to reduce z-fighting in the cockpit.

Parameters

[out] output4x4 4x4 vc projection matrix

GetPickResult

void GetPickResult	(	int	ID,	[out]	bool&	wasHit,	[out]	float&	distanceToHit
	)		const

Get hit result. A pick request must first be requested using AddPickRequest on a WindowPdk interface from within an window callback. The ID passed in should be the ID that was returned from the AddPickRequest call.

Parameters

ID	ID of hit request to get results. This value is returned from AddPickRequest.
[out]	wasHit,	Will be set true if the pick result hit a pickable object and false if not
[out]	distanceToHit	If hit test passed, the distance to the hit in meters will be stored.

GetAvatarMode

int GetAvatarMode ( ) const

Get the AvatarMode for the current window.

Returns: The AvatarMode of the current window. (0 = None, 1 = First, 2 = Third)

GetLLARadians

void GetLLARadians	(	double &	lat,
		double &	lon,
		double &	alt
	)		const

Get the offset of the latitude longitude and altitude of the camera in radians

Parameters

[out]	lat	Latitude
[out]	lon	Longitude
[out]	alt	Altitude

GetTargetLatLonAltDegrees

void GetTargetLatLonAltDegrees	(	double &	lat,
		double &	lon,
		double &	alt
	)		const

Gets the target LLA of the camera in degrees.

Parameters

[out]	lat	Latitude
[out]	lon	Longitude
[out]	alt	Altitude

GetTargetContainerId

void GetTargetContainerId ( unsigned int & containerId ) const

Gets the target container ID of the tracked entity.

Parameters

[out] containerId Container ID

GetSensorMode

void GetSensorMode ( unsigned int & sensorMode ) const

Gets the sensor mode of the camera.

Parameters

[out] sensorMode Sensor Mode

GetCameraLookAtLLA

void GetCameraLookAtLLA	(	double &	lat,
		double &	lon,
		double &	alt
	)		const

Gets the LLA the camera is currently looking at in degrees. If the camera is not looking at a valid LLA (i.e. centered at the sky) then false is returned.

Parameters

[out]	lat	Latitude
[out]	lon	Longitude
[out]	alt	Altitude

Returns: Whether or not the camera is viewing a valid LLA

IsGlobalRotate

bool IsGlobalRotate ( ) const

Gets whether or not the camera is rotating relative to the world or the user vehicle.

Returns: The whether or not global rotation is enabled

GetGlobalPBH

void GetGlobalPBH	(	float &	p,
		float &	b,
		float &	h
	)		const

Get the global orientation of the camera (Pitch, Bank, and Heading) when SetGlobalRotate is enabled

Parameters

[out]	p	Pitch
[out]	b	Bank
[out]	h	Heading

GetTargetLatString

void GetTargetLatString ( char* targetLat ) const

Gets the target latitude in string format

Parameters

[out] targetLat Latitude

GetTargetLonString

void GetTargetLonString ( char* targetLon ) const

Gets the target longitude in string format

Parameters

[out] targetLon Longitude

GetPickTextureLocation

void GetPickTextureLocation	(	int	ID,
		char*	windowName,
		bool &	wasHit
		float &	u
		float &	v
		float &	distanceToHit
	)		const

Get the texture coords that the pick hit on the texture in the specified window. A pick request must first be requested using AddPickRequest on a WindowPdk interface from within an window callback. The ID passed in should be the ID that was returned from the AddPickRequest call.

Parameters

[in]	ID	ID of the hit request
[in]	windowName	Name of window texture resides within.
[out]	wasHit	true if hit test passed
[out]	u	u location in texture
[out]	v	v location in texture
[out]	distanceToHit	distance to texture hit

IWindowCallback

Callback function used by window plug-ins

Invoke

void Invoke ( IUnknown * cbData )

This function is called when the callback is invoked by Prepar3D. This is called just after the camera computations but prior to rendering. The supported interfaces for this are:

IWindowPdk - Interface for setting values on a window.
IWindowReaderPdk - Read only interface for getting values from a window
IWindowPluginSystem - Plug-in system that Invoked the callback (currently only supported for flight loaded callbacks)

Parameters

cbData callback data object which can be queried for supported interfaces

InvokePreCamera

void InvokePreCamera ( IUnknown * cbData )

This function is called when the callback is invoked by Prepar3D. This is called just prior to the camera computations, including position and orientation, for this window. NOTE: This function is only available in version 2 of this interface (IWindowCallbackV02) and later. (The supported interfaces for this are:

IWindowPdk - Interface for setting values on a window.
IWindowReaderPdk - Read only interface for getting values from a window
IWindowPluginSystem - Plug-in system that Invoked the callback (currently only supported for flight loaded callbacks)

Parameters

cbData callback data object which can be queried for supported interfaces

ICustomInputCallback

Callback function used by window plug-ins four input handling

CustomInputProc

bool CustomInputProc	(	HWND	window,
		unsigned int	message,
		WPARAM	wParam,
		LPARAM	lParam
	)

Custom input handling function. The parameters are passed along from the Operating System. Refer to Microsoft's documentation on Window Procedures for more information on input message handling.

Parameters

window	Handle to window
message	Message identifier
wParam	first message parameter
cb	second message parameter

Returns: bool, Clients should return true if they've handled the message and don't want it to propagate to the window.

IMouseRectListenerCallback

Callback function used to receive mouse rectangle click events. This callback can be registered and unregistered via the IWindowPluginSystem.

MouseRectListenerProc

void MouseRectListenerProc	(	UINT	id,
		MOUSE_CLICK_TYPE	clickType
	)

Mouse rectangle click callback function. This function will be called when an IMouseRectListenerCallback is registered with the IWindowPluginSystem.

Parameters

id	The id of the mouse rectangle click event.
MOUSE_CLICK_TYPE	The click type received by the mouse rectangle.

IPluginSystem

Plug-in system for getting or creating rendering plug-ins

GetOrCreatePlugin

HRESULT GetOrCreatePlugin	(	REFIID	id,
		void **	plugin
	)

Get or create plug-in

Parameters

	id	Interface ID
[out]	pointer	to hold plug-in that is created or retrieved

ITextureRenderPlugin

Plug-in interface used to register a texture by name and render into it. These textures can be mapped to models and gauges by name the same way the texture files are mapped by file name.

CreateTexture

HRESULT CreateTexture	(	const char *	name,
		unsigned int	width,
		unsigned int	height,
		ICustomRenderCallback *	cb
	)

Create a new texture given name, size, and a callback function for each update

Parameters

name	Name of texture. Models and gauges can map to this texture by name.
width	Width of texture in pixels
height	Height of texture in pixels
cb	Callback that will be used by the plug-in to render into the texture

Returns: HRESULT, S_OK if function succeeds

RemoveTexture

HRESULT RemoveTexture ( const char * name )

Remove a texture given the texture name

Parameters

name	Name of plug-in

Returns: HRESULT, S_OK if function succeeds

GetCreatedTexture

HRESULT GetCreatedTexture ( std::list< std::string > & nameList )

Get list of textures created externally

Parameters

[out] nameList list of names of all plug-ins

IEffectsRenderPlugin

Plug-in interface used to render directly into a window/view. This kind of plug-in can be used to draw new content on top of a window. If requested, the plug-in can also read from the current view output allowing it to implement post process effects that are too complex to be implemented through the xml/hlsl based custom post process system.

CreateEffect

HRESULT CreateEffect	(	const char *	name,
		ICustomRenderCallback *
	)

Create a new effect with given name and a callback function for each update

Parameters

name	Name of Effect
cb	Callback that will be used by the plug-in to render the effect

Returns: HRESULT, S_OK if function succeeds

RemoveEffect

HRESULT RemoveEffect ( const char * name )

Remove an effect with given name that was created externally

Parameters

name	Name of Effect

Returns: HRESULT, S_OK if function succeeds

GetSystemEffects

HRESULT GetSystemEffects ( std::list< std::string > & nameList )

List of effects provided by the system

Parameters

nameList standard list of strings containing effect names

Returns: HRESULT, S_OK if function succeeds

GetSystemEffects

HRESULT GetSystemEffects	(	char **	names,
		int &	count
	)

List of effects provided by the system

Parameters

[out]	names	list of names of effects provided by the system
[out]	size	number of items in the list

Returns: HRESULT, S_OK if function succeeds

ICustomRenderCallback

Render callback used by both effect and texture plug-ins.

Render

void Render ( IUnknown * cbData )

A callback to render content. The supported interfaces for this are:

IRenderData - Provides information about the view. See IRenderData section of this document.
ID3D11Device - The ID3D11Device the view is rendering on
ID3D11RenderTargetView - RenderTargetView for rendering into
ID3D11ShaderResourceView - ShaderResourceView for reading current view output as texture. In order to use this, the plug-in should override RequiresDoubleBuffer and return true.
ID3D11DepthStencilView - DepthStencilView for depth testing. (Will not work if anti-aliasing is enabled because the depth format no longer matches the render target format after the render target is resolved)

Parameters

cbData IUnknown object that can be query for specific object implementation.

HasUpdate

bool HasUpdate ( )

Indicate that there is updated information to be drawn.

Returns: FALSE will bypass the Render Callback for 1 frame.

Remarks: For texture plug-ins, the resource is double-buffered and is swapped after each render. A plug-in developer can optimize the plug-in to only when the data changes or at a lower update rates, but must override this function to return false on frames where no changes were made so that Prepar3D does not swap buffers and cause flickering artifacts.

RequiredDoubleBuffer

bool RequiredDoubleBuffer ( )

Override this method in an effect plug-in will specify double buffering. This will give the callback both output render target and a shader resource as input.

Returns: return true to require double buffering

Remarks: Texture plug-ins are always double buffered so this function is ignored.

IsPreVc

bool IsPreVc ( )

Override this method to specify if effect should draw before the virtual cockpit

Returns: return true to apply this plug-in before the virtual cockpit renders

RequestTextures

void RequestTextures	(	const char **	names,
		unsigned int &	uCount
	)

Override this method to request additional input for this frame. This interface can also be used to request depth stencil buffer as well. Use this assign key word for depth stencil: DEPTH_STENCIL_BUFFER

Parameters

[out]	names	The texture names.
[in,out]	uCount	The maxcount of the char* list

Remarks: This must the name of texture plug-in or render to texture view defined in the Camera.CFG

IsDeferedRenderingSafe

bool IsDeferedRenderingSafe ( )

Override this method to disable deferred context rendering. Prepar3D can be configured to do rendering on a Deferred Context to enable threading and optimization. Some plug-ins may required access to the Immediate Context to do their rendering. If so, override this function and return false.

Returns: False if this plug-in cannot render on a deferred context

IRenderData

Interface to get data available to plug-ins in the render callback.

GetTextureWidth

FLOAT GetTextureWidth ( )

Get Texture width

Returns: Texture width in pixels

GetTextureHeight

FLOAT GetTextureHeight ( )

Get Texture height

Returns: Texture height in pixels

GetAdapterID

UINT GetAdapterID ( )

Get adapter id of the video card that this plug-in is currently rendering on. Note that for multi-GPU support. Plug-ins either need to create all resources each time render is called, or check this value and allocate resources for each GPU.

Returns: UINT, Adapter ID index

QueryResource

HRESULT QueryResource	(	const char *	name,
		REFIID	iid,
		PVOID *	output
	)

This function query for a resource that is previously requested See RequestTextures, RequestDepthStencil

Parameters

	name	Name of the resource
	iid	Interface ID
[out]	output	Output pointer

Returns: E_FAIL if no resource found with with given name E_NOINTERFACE if resource name found, but Interface ID do not match S_OK if the request is valid

IObjectRenderer

Service for custom object rendering into a Prepar3D view.

BeginLightGroup

HRESULT BeginLightGroup ( const ObjectWorldTransform groupOrigin )

Begin light group

Parameters

groupOrigin World transform for the light group origin. Lights added to the group will be positioned body relative to this origin.

Returns: S_OK if function succeeds, E_FAIL if not.

EndLightGroup

HRESULT EndLightGroup ( bool doSort )

End light group. Call this after all lights have been added.

Parameters

doSort If true, light group will be sorted with other transparent objects such as clouds. If false, light group is assumed to be on the ground, and is not sorted. Groups that are not sorted can be combined into a single draw call be the Prepar3D engine to improve rendering performance.

Returns: S_OK if function succeeds, E_FAIL if not.

AddLight

HRESULT AddLight	(	float	x,
		float	y,
		float	z,
		unsigned int	lightType,
		unsigned int	color,
		float	size,
		float	range,
		bool	bAttenuateByAmbient	)

Add Light to a light group

Parameters

	x	x offset of light body relative to group origin.
	y	y offset of light body relative to group origin.
	z	z offset of light body relative to group origin.
	lightType	Type of light. 0: Point, 1: Big Halo, 2: Spot, 3: Small Halo.
	color	light color in ARGB format.
	size	Size of light. Size is only apparent at close range.
	range	distance in meters at which light can be seen.
	bAttenuateByAmbient	Attenuate brightness based on ambient lighting.

Returns: S_OK if function succeeds, E_FAIL if not.

ApplyBodyRelativeOffset

void ApplyBodyRelativeOffset	(	const ObjectWorldTransform	llapbhAtOrigin,
		const ObjectLocalTransform	offsetXyzPbh,
		ObjectWorldTransform	llapbhAtOffset )

Apply body-relative offset to a given world transform.

Parameters

	llapbhAtOrigin	The world transform to apply the offset
	offsetXyzPbh	xyz and pbh body relative offset to apply.
	llapbhAtOffset	out parameter which will contain the calculated lla and pbh world transformation at the offset location.

CalculateBodyRelativeOffset

void CalculateBodyRelativeOffset	(	const ObjectWorldTransform	llapbhAtOrigin,
		const ObjectWorldTransform	llapbhAtOffset )
		ObjectLocalTransform	offsetXyzPbh,

Calculate the body-relative offset between two world transforms.

Parameters

	llapbhAtOrigin	The world transform of the origin
	llapbhAtOffset	The world transform at the offset
	offsetXyzPbh	Out parameter which will contain the calculated xyz and pbh body relative offset to get from the origin to the offset transform.

LLADegreesMeters

struct LLADegreesMeters
{
     double Latitude;
     double Longitude;
     double Altitude;

     LLADegreesMeters() : Latitude(0.0), Longitude(0.0), Altitude(0.0) {}
     LLADegreesMeters(double latitude, double longitude, double altitude)
         : Latitude(latitude), Longitude(longitude), Altitude(altitude) {}
};

World position including latitude longitude and altitude

Members

	Latitude	Latitude in degrees
	Longitude	Longitude in degrees
	Altitude	Altitude in meters.

PBHDegrees

struct PBHDegrees
{
     float Pitch;
     float Bank;
     float Heading;

     PBHDegrees() : Pitch(0.0f), Bank(0.0f), Heading(0.0f) {}
     PBHDegrees(float pitch, float bank, float heading)
         : Pitch(pitch), Bank(bank), Heading(heading) {}
};

Orientation pitch, bank, and heading

Members

	Pitch	Pitch in degrees
	Bank	Bank in degrees
	Heading	Heading in degrees.

XYZMeters

struct XYZMeters
{
     float X;
     float Y;
     float Z;

     XYZMeters() : X(0.0f), Y(0.0f), Z(0.0f) {}
     XYZMeters(float x, float y, float z) : X(x), Y(y), Z(z) {}
};

Position offset in meters

Members

	X	X offset in meters.
	Y	Y offset in meters.
	Z	Z offset in meters.

ObjectWorldTransform

struct ObjectWorldTransform
{
     LLADegreesMeters LLA;
     PBHDegrees PBH;

     ObjectWorldTransform(){}
     ObjectWorldTransform(double latitude, double longitude, double altitude,
         float pitch, float bank, float heading)
        : LLA(latitude, longitude, altitude), PBH(pitch, bank, heading) {}
};

World transformation containing position and orientation.

Members

	LLA	Position latitude and longitude in degrees, altitude in meters.
	PBH	Orientation pitch, bank, and heading in degrees.

ObjectLocalTransform

struct ObjectLocalTransform
{
     XYZMeters XYZ;
     PBHDegrees PBH;

     ObjectLocalTransform(){}
     ObjectLocalTransform(float x, float y, float z, float pitch, float bank, float heading)
         : XYZ(x, y, z), PBH(pitch, bank, heading) {}
};

Local transformation containing position and orientation.

Members

	XYZ	Local position offset XYZ in meters.
	PBH	Local orientation pitch, bank, and heading in degrees.

- top -