Weather Access

Get the last-downloaded METAR report for an airport by ICAO code. Note that the actual weather at that airport may have evolved significantly since the last downloaded METAR. outMETAR must point to a char buffer of at least 150 characters. THIS CALL DOES NOT RETURN THE CURRENT WEATHER AT THE AIRPORT, and returns an empty string if the system is not in real-weather mode.

This call is not intended to be used per-frame. It should be called only during the pre-flight loop callback.

XPLMGetMETARForAirport(
    airport_id,    -- string
    outMETAR       -- see XPLMFixedString150_t
)

Get the current weather conditions at a given location. Note that this does not work world-wide, only within the surrounding region. Return true if detailed weather (i.e. an airport-specific METAR) was found, false if not. In both cases, the structure will contain the best data available.

IMPORTANT: When you read the weather at a given point you are reading the OUTPUT from the internal weather simulation, the exact details of which are undocumented. Never expect to read the exact numbers you may have set, even at the same coordinates.

This call is not intended to be used per-frame. It should be called only during the pre-flight loop callback.

-- returns boolean -> assign to local/var
local my_result = XPLMGetWeatherAtLocation(
    latitude,      -- float
    longitude,     -- float
    altitude_m,    -- float
    out_info       -- see XPLMWeatherInfo_t
)

See associated types:

• XPLMWeatherInfo_t

Inform the simulator that you are starting a batch update of weather information. If you are providing multiple weather updates, using this call may improve performance by telling the simulator not to update weather until you are done.

This call is not intended to be used per-frame. It should be called only during the pre-flight loop callback. You must call XPLMEndWeatherUpdate before you return from the callback; XPLMBeginWeatherUpdate in one callback and XPLMEndWeatherUpdate in a later callback, even within the same frame, is not permitted.

XPLMBeginWeatherUpdate(
)

Inform the simulator that you are ending a batch update of weather information. If you have called XPLMBeginWeatherUpdate, you MUST call XPLMEndWeatherUpdate before exiting your callback otherwise any accumulated weather data will be discarded.

When using incremental mode, any changes made are applied to your existing data. This makes it possible to only update a fraction of your weather data at any one time. When not using incremental mode, ALL reports previously passed by your plugin are erased before applying new data.

When using any of these 'weather set' APIs, the normal mode of operation is that you are setting the weather in the near future. Currently this is somewhere between one and two minutes but do not rely on this remaining the same.

Setting future weather ensures that there is no sudden jump in weather conditions when you make a change mid-cycle. In some situations, notably for an initial setup, you may want to ensure that the weather is changed instantly. To do this, set 'updateImmediately' as true.

isIncremental : If true, append or modify existing records created by your plugin. If false, clear any existing records. updateImmediately : If true, immediately reset and recalculate the weather. If false, your new data will be used when the weather next recalculates.

This call is not intended to be used per-frame. It should be called only during the pre-flight loop callback.

XPLMEndWeatherUpdate(
    isIncremental,        -- boolean
    updateImmediately     -- boolean
)

Set the current weather conditions at a given location on the ground and above it.. Please see the notes on individual fields in XPLMSetWeatherAtAirport, and notes on timing in XPLMEndWeatherUpdate.

The ground altitude passed into this function call does not set the area of influence of this weather vertically; the weather takes effect from 0 MSL ground up to the passed-in max_altitude_msl_ft. The ground altitude passed in is the elevation of the reporting station to calibrate QNH.

IMPORTANT: As with all calls to set weather, you are setting one aspect to be used in a much wider atmospheric simulation. Never expect to get the same numbers back from a read, even at the same locations, since the XPLMGetWeather... calls all read the simulated state, not any particular input. This applies equally to static and real-weather modes.

This call is not intended to be used per-frame. It should be called only during the pre-flight loop callback.

XPLMSetWeatherAtLocation(
    latitude,               -- float
    longitude,              -- float
    ground_altitude_msl,    -- float
    in_info                 -- see XPLMWeatherInfo_t
)

See associated types:

• XPLMWeatherInfo_t

Erase weather conditions set by your plugin at a given location. You must give exactly the same coordinates that you used to create a weather record at this point. It does NOT mean 'create clear weather at this location'.

This call is not intended to be used per-frame. It should be called only during the pre-flight loop callback.

XPLMEraseWeatherAtLocation(
    latitude,     -- float
    longitude     -- float
)

Set the current weather conditions at a given airport. Unlike XPLMSetWeatherAtLocation, this call will replace any existing weather records for that airport from other sources (i.e. downloaded METARs) instead of being used as just another weather sample.

Some notes on individual fields: - pressure_alt should be QNH as reported by a station at the specified airport, or 0 if you are passing sealevel pressure in 'pressure_sl' instead. - pressure_sl is ignored if pressure_alt is given. - wind_dir_alt, wind_spd_alt, turbulence_alt, wave_speed, wave_length are derived from other data and are UNUSED when setting weather. - Temperatures can be given EITHER as a single temperature at the ground altitude (temperature_alt) OR, if the struct is V2 or higher, as an array of temperatures aloft (temp_layers). If you pass a value for temperature_alt higher than -273.15 (absolute zero), that will be used with the altitude value to calculate an offset from ISA temperature at all altitudes. Any layer in temp_layers for which you set the temperature higher than -273.15 (absolute zero) will use that temperature and all others will use the existing value for the location, or the calculated values from temperature_alt if you also passed that. It is advised to use a lower value than exactly -273.15 to avoid floating-point precision errors. These calculated temperatures during a read are also affected by the troposphere altitude and temperature, and the vertical radius of effect. If you set both temperature_alt (V1 single value) and temp_layers (V2 per-layer value) then the more detailed V2 data, if valid, will override the values calculated from the older, ground-level only temperature value. - The same rules apply to dewpoint temperatures; either a single value at ground level in 'dewpoint_alt', or per-layer values in 'dewp_layers'. - The troposphere altitude and temperature will be derived from existing data if you pass 0 or lower for troposphere_alt. Both altitude and temperature may be clamped to internally-defined ranges. - When setting both temperature and dewpoint from a single value (temperature_alt/dewpoint_alt), the rest of the atmosphere will be graded to fit between the given values and the troposphere.

IMPORTANT: As with all calls to set weather, you are setting one aspect to be used in a much wider atmospheric simulation. Never expect to get the same numbers back from a read, even at the same locations, since the XPLMGetWeather... calls all read the simulated state, not any particular input. This applies equally to static and real-weather modes.

This call is not intended to be used per-frame. It should be called only during the pre-flight loop callback.

XPLMSetWeatherAtAirport(
    airport_id,    -- string
    in_info        -- see XPLMWeatherInfo_t
)

See associated types:

• XPLMWeatherInfo_t

Erase the current weather conditions set by your plugin at a given airport, allowing records from other sources to be used. It does NOT mean 'create clear weather at this airport'.

This call is not intended to be used per-frame. It should be called only during the pre-flight loop callback.

XPLMEraseWeatherAtAirport(
    airport_id     -- string
)