Radar Simulation and Visualization Service

Contents

Overview
Radar XML Interface
Radar Panel Callback Example
Radar C++ Interface Reference

Overview

Prepar3D provides an air-to-ground radar simulation and visualization service for developers. Because every radar system is different, the Prepar3D radar is provided as a highly configurable service which can be controlled via C++ plug-ins and XML gauges. Some examples of controllable parameters are: Range, Sweep Angle, Sweep Rate, Zoom Level, Image, and Data resolution. Some of the advanced capabilities of the Prepar3D radar include accurate radar shadows, far-shore-enhancement, and Doppler-beam-sharpening. Also, we developed the radar service entirely through our SDK to showcase the power and flexibility that 3rd party developers have when developing content specifically for Prepar3D v3.

Radar XML Interface

The quickest and simplest way to get up and running using the Prepar3D radar is to write an XML gauge using the C:P3DRadar variables provided by the P3DRadar IPanelCallback. This panel callback is loaded automatically, so there is no need to add a dll to the DLL.XML. A sample gauge that uses most of the provided functionality is included in the core application gauges folder (gauges\P3DRadar\radar.xml). To add Prepar3D's sample radar gauge to a SimObject, simply open up the SimObject's panel.cfg and add a panel entry that references the P3DRadar:radar gauge:

[Window Titles]
Window00=Radar
[Window00]
size_mm=265,310
Background_color=1,1,1
visible=0
position=8
windowsize_ratio=0.4
gauge00=P3DRadar!Radar, 5, 5, 255, 305

To extend the example or write new XML gauges based on this interface, refer to the full list of C:P3DRadar variables below.

P3DRadar C Variable	Description	Units	Settable	Multiplayer
ClearRadarImage	Set non zero value to trigger a radar image clear.	Number	Y	N
ShowRangeRings	1 - Show range rings 0 - Hide range rings	Number	Y	N
ShowCursor	1 - Show Cursor 0 - Hide Cursor	Number	Y	N
FarShoreEnhance	1 - Enable Far Shore Enhancement 0 - Disable Far Shore Enhancement	Number	Y	N
VisualZoom	Zoom in on radar display. Display is centered on current cursor position. Values less than 1.0 are not supported.	Number	Y	N
DataZoom	Remap radar sensor coverage to area surrounding the current cursor position to increase data resolution. When set to the same value as visual zoom, this works well as an approximation of Doppler Beam Sharpening. Values less than 1.0 are not supported.	Number	Y	N
ScanAzimuth	Maximum deviation from center of the radar system sweep. Valid Range is 1.0-60.0.	Number	Y	N
SweepRate	Sweep rate in degrees per second	Number	Y	N
RangeMiles	Maximum range of radar in Nautical Miles.	Number	Y	N
RenderingEnabled	The effectively disables the radar service. This should be set to 0 when not displaying the radar texture element with the radar for best performance. 1 - Enable rendering 0 - Disable rendering	Number	Y	N
FreezeEnabled	1 - Enable Image and Radar Beam Freeze 0 - Disable Image and Radar Beam Freeze	Number	Y	N
CursorPositionX	Set cursor horizontal cursor location. The range 0.0-1.0 maps from left to right across the extents of the un-zoomed radar gauge image. Zoom calculation must be done by developer.	Number	Y	N
CursorPositionY	Set cursor vertical cursor location. The range 0.0-1.0 maps from top to bottom down the extents of the un-zoomed radar gauge image. Zoom calculation must be done by developer.	Number	Y	N
CursorPositionLat	Latitude of cursor position. Actual cursor position in radar is relative to display. Getting or setting this value will trigger conversions in the C++. For best results set Latitude and Longitude in pairs.	Number	Y	N
FrontBlindSpotDegrees	Width of the current front blindspot in degrees. This is generally only used for Doppler Beam Sharpening and should otherwise be set to 0.	Number	Y	N
SideBlindSpotDegrees	Width of the current side blindspot in degrees. This is generally only used for Doppler Beam Sharpening and should otherwise be set to 0.	Number	Y	N
RadarResolutionX	Horizontal resolution of radar data texture.	Number	Y	N
RadarResolutionY	Vertical resolution of radar data texture.	Number	Y	N
GaugeResolutionX	Horizontal resolution of radar gauge texture in pixels.	Number	Y	N
GaugeResolutionY	Vertical resolution of radar gauge texture in pixels.	Number	Y	N
CurrentRadarBeamOffset	Get the current angular offset of the radar beam. Read-only value determined by radar simulation.	Number	N	N
CurrentRadarScanElevationDegrees	Current elevation of the radar beam in degrees. Read-only value set by radar system. This value will vary by altitude, range, and data zoom.	Number	N	N

Radar Panel Callback Example

For more advanced use cases, the Prepar3D radar can be controlled via C++ using the ISimulatedRadar PDK Service. One possible use case for this would be to provide a customized IPanelCallback that extends the capabilities of the P3DRadar callback provided by Prepar3D. The Radar Callback Sample is a great starting point for this use case and can be found here:

<Prepar3D SDK Path>\Utilities\PDK\RadarPanelCallbackSample
The Radar Callback Sample source can be viewed here. The Radar Callback Sample is a mixed mode gauge example similar to the CabinComfort example found in the Panels and Gauges SDK but it is far more advanced. The PanelCallback in the sample is functionally equivalent to the PanelCallback provided by the core radar service, so it is a perfect starting point for extending the existing XML interface. Controlling the radar from C++ provides more flexibility and higher performance, and can greatly simplify the XML scripting required to create a robust radar gauge. Interfacing via C++ also can allow multiple add-ons to interface with the radar which may be required to simulate more advanced aircraft. Consult the ReadMe file in the example folder for further instructions on how to install and use it.

Radar C++ Interface Reference

This section covers the functions provided by the ISimulatedRadar service interface. The service can be requested from the PDK as shown in the following code sample taken from the RadarPanelCallback sample:

extern "C"
{
    void __stdcall DLLStart( __in __notnull P3D::IPdk* pPdk )
    {
        if( pPdk != nullptr && Panels != nullptr)
        {
            // Check for radar interface
            ISimulatedRadar* pRadar;
            pPdk->QueryService( Radar::IID_ISimulatedRadar, &pRadar );
            if( pRadar != nullptr )
            {
                // create panel callback passing in the radar service pointer
                RadarPanelCallback * pPanelCallback = new RadarPanelCallback( pRadar );
                // hook up the panels table for good measure even though its not being used
                ImportTable.PANELSentry.fnptr = (PPANELS)Panels;
                // register the panel callback by name for mixed mode C: variables
                panel_register_c_callback( RADAR_EXAMPLE_CALLBACK_NAME, pPanelCallback);
                // clean up local ref counted resources
                pPanelCallback->Release();
                pRadar->Release();
            }
        }
        return;
    }
}

Once a plug-in has successfully queried the PDK for the radar interface, the following interface functions can be used to control it:

ClearRadarImage

void ClearRadarImage ( )

Clear the radar image on update

DeInit

HRESULT DeInit ( void )

Deinit the radar system

FarShoreEnhance

bool FarShoreEnhance ( ) const

Is the radar image enhancing far shore pixels

Returns: Far shore enhancement enabled

FreezeEnabled

bool FreezeEnabled ( ) const

Is the radar beam actively sweeping and updating its intermediate texture? Note: When in freeze mode, the radar camera and intermediate texture compositing is disabled, but the gauge is still rendered

Returns: Radar is actively sweeping

GetCurrentRadarBeamOffsetDegrees

double GetCurrentRadarBeamOffsetDegrees ( ) const

Get the current angular offset of the radar beam

Returns: Beam offset in degrees

GetCurrentRadarScanElevationDegrees

double GetCurrentRadarScanElevationDegrees ( ) const

Get the current elevation of the radar beam in degrees

Returns: Elevation of radar beam

GetCursorPositionLLA

void GetCursorPositionLLA ( LLA & lla ) const

Get the LLA of the current cursor position

Parameters

lla	Out variable for the current LLA of the radar cursor

GetCursorPositionXY

void GetCursorPositionXY	(	double &	x,
		double &	y
	)		const

Get the current x and y coordinates of the cursor

Parameters

x	Out variable for X coordinate of cursor
y	Out variable for y coordinate of cursor

GetDataZoom

double GetDataZoom ( ) const

Get the current level of data zoom

Returns: Data zoom

GetFrontBlindspotDegrees

double GetFrontBlindspotDegrees ( ) const

Get the width of the current front blindspot in degrees This will usually be 0 unless the radar is in a DBS mode

Returns: Width of front blindspot in degrees

GetGaugeResolution

void GetGaugeResolution	(	double &	x,
		double &	y
	)		const

Get the resolution of the radar gauge

Parameters

x	Width of radar gauge
y	Height of radar gauge

GetRadarResolution

void GetRadarResolution	(	double &	x,
		double &	y
	)		const

Get the resolution of the radar image

Parameters

x	Width of radar image
y	Height of radar image

GetRangeMiles

double GetRangeMiles ( ) const

Get the current range setting of the radar system in miles

Returns: Radar range setting, in miles

GetScanAzimuth

double GetScanAzimuth ( ) const

Get the maximum deviation from center of the radar system sweep. Valid range is 1.0-60.0.

Returns: Sweep azimuth

GetSideBlindspotDegrees

double GetSideBlindspotDegrees ( ) const

Get the width of the current side blindspots in degrees This will usually be 0 unless the radar is in a DBS mode This width is measured from the maximum extents of the current azimuth

GetSweepRate

double GetSweepRate ( ) const

Get the rate at which the radar system sweeps side to side

Returns: Sweep rate in degrees per second

GetVisualZoom

double GetVisualZoom ( ) const

Get the current visual zoom level

Returns: Visual zoom

Init

HRESULT Init	(	const char *	sRenderToTextureName,
		UINT	width,
		UINT	height
	)

Initialize the radar system with the specified RTT name, and resolution

Parameters

sRenderToTextureName	Name of RTT texture
width	Initial width for radar image and gauge
height	Initial height for radar image and gauge

IsInitialized

bool IsInitialized ( ) const

Returns true if radar system has been initialized.

NeedsUpdate

bool NeedsUpdate ( ) const

Since gauges might outpace framerate, gauge code should ensure that the radar System is not in need of an update before re-doing any work.

RenderingEnabled

bool RenderingEnabled ( ) const

Is the radar currently rendering to the intermediate and final gauge texture? Note: the radar camera is still updated, along with radar variables

Returns: Internal gauge rendering enabled

SetCursorPositionLLA

void SetCursorPositionLLA ( const LLA & lla )

Set the cursor over the specified Lat Lon Alt

Parameters

lla	New latlonalt of cursor, note that this must fall within radar picture

SetCursorPositionXY

void SetCursorPositionXY	(	double	dX,
		double	dY
	)

Set the cursor position with local x and y coordinates X and Y are 0-1, top-left to bottom-right of radar display.

Parameters

dX	Local x coordinate
dY	Local y coordinate

SetDataZoom

void SetDataZoom ( double dataZoom )

Set the data zoom level Increasing visual zoom will improve resolution by reducing the area covered

Parameters

dataZoom Data zoom level

SetFarShoreEnhancementEnabled

void SetFarShoreEnhancementEnabled ( bool enabled )

Set far shore enhancement enabled

Parameters

enabled Enable far shore enhancement

SetFreeze

void SetFreeze ( bool freeze )

Set whether the radar is upading the sweep of the beam and intermediate texture

Parameters

freeze Radar freeze mode enabled

SetFrontBlindSpotDegrees

void SetFrontBlindSpotDegrees ( double frontBlindSpot )

Set the front DBS blindspot width

Parameters

frontBlindSpot New width of front blindspot in degrees

SetRadarGaugeResolution

void SetRadarGaugeResolution	(	double	resolutionX,
		double	resolutionY
	)

Set the resolution of the gauge being rendered into. If the gauge resolution is set incorrectly the radar image will not display properly.

Parameters

resolutionX	New width for gauge image
resolutionY	New height for gauge image

SetRadarImageResolution

void SetRadarImageResolution	(	double	resolutionX,
		double	resolutionY
	)

Set the resolution of the radar's internal texture.

Parameters

resolutionX	New width for radar image
resolutionY	New height for radar image

SetRangeMiles

void SetRangeMiles ( double range )

Set the range of the radar system in miles

Parameters

range New radar rang in miles

SetRenderingEnabled

void SetRenderingEnabled ( bool enabled )

Set whether the radar system is updating its intermediate texture and the final gauge image

Parameters

enabled Radar rendering enabled

SetScanAzimuthDegrees

void SetScanAzimuthDegrees ( double azimuth )

Set the maximum extent of the radar sweep

Parameters

azimuth New azimuth in degrees

SetScanRateDegreesPerSecond

void SetScanRateDegreesPerSecond ( double rate )

Set the scan rate of the radar beam

Parameters

rate	New sweep rate

SetShowCursor

void SetShowCursor ( bool enabled )

Set cursor drawing enabled

Parameters

enabled Enable simple cursor display

SetShowRangeRings

void SetShowRangeRings ( bool show )

Set range rings enabled

Parameters

show	Enable range ring display

SetSideBlindSpotDegrees

void SetSideBlindSpotDegrees ( double sideBlindSpots )

Set the width of the side DBS blindspots

Parameters

sideBlindSpots New width of side blind spots

SetVisualZoom

void SetVisualZoom ( double visualZoom )

Set the visual zoom level Increasing visual zoom is equivalent to zooming on a fixed resolution image

Parameters

visualZoom Visual zoom level

ShowCursor

bool ShowCursor ( ) const

Is cursor drawing enabled?

Returns: Cursor enabled

ShowRangeRings

bool ShowRangeRings ( ) const

Is range-ring display enabled?

Returns: Range-rings enabled

- top -