Interface ICWFGM Grid Engine. More...
import "GridCOM.idl";
Public Member Functions | |
HRESULT | MT_Lock ([in] __int64 layerThread, [in] unsigned short exclusive, [in] unsigned short obtain) |
HRESULT | Valid ([in] __int64 layerThread, [in] unsigned __int64 start_time, [in] __int64 duration, [in] unsigned long option, [in, out] SAFEARRAY(unsigned short)*application_count) |
HRESULT | GetAttribute ([in] __int64 layerThread, [in] unsigned short option, [out, retval]VARIANT *value) |
HRESULT | GetDimensions ([in] __int64 layerThread, [out] unsigned short *x_dim, [out]unsigned short *y_dim) |
HRESULT | GetFuelData ([in] __int64 layerThread, [in] unsigned short _x, [in] unsigned short _y, [in] unsigned __int64 time, [out, retval]ICWFGM_Fuel **fuel) |
HRESULT | GetFuelIndexData ([in] __int64 layerThread, [in] unsigned short x, [in] unsigned short y, [in] unsigned __int64 time, [out, retval]unsigned char *fuel_index) |
HRESULT | GetElevationData ([in] __int64 layerThread, [in] unsigned short x, [in] unsigned short y, [in] short allow_defaults_returned, [out]double *elevation, [out] double *slope_factor, [out] double *slope_azimuth) |
HRESULT | GetAttributeData ([in] __int64 layerThread, [in] unsigned short x, [in] unsigned short y, [in] unsigned __int64 time, [in] unsigned short option, [out, retval] VARIANT *attribute) |
HRESULT | GetWeatherData ([in] __int64 layerThread, [in] unsigned short x, [in] unsigned short y, [in] unsigned __int64 time, [in]unsigned long interpolate_method, [out]IWXData *wx, [out]IFWIData *ifwi, [out]DFWIData *dfwi) |
HRESULT | GetFuelDataArray ([in] __int64 layerThread, [in] unsigned short _x_min, [in] unsigned short _y_min, [in] unsigned short _x_max, [in]unsigned short _y_max,[in]unsigned __int64 time, [in, out] SAFEARRAY(ICWFGM_Fuel *)*fuel) |
HRESULT | GetFuelIndexDataArray ([in] __int64 layerThread, [in]unsigned short _x_min, [in]unsigned short _y_min, [in]unsigned short _x_max, [in]unsigned short _y_max, [in]unsigned __int64 time, [in, out] SAFEARRAY(unsigned char)*fuel_index) |
HRESULT | GetElevationDataArray ([in] __int64 layerThread, [in]unsigned short x_min, [in]unsigned short y_min, [in]unsigned short x_max, [in]unsigned short y_max, [in]short allow_defaults_returned, [in, out] SAFEARRAY(double)*elevation, [in, out] SAFEARRAY(double)*slope_factor, [in, out] SAFEARRAY(double)*slope_azimuth) |
HRESULT | GetWeatherDataArray ([in] __int64 layerThread, [in]unsigned short x_min, [in]unsigned short y_min, [in]unsigned short x_max, [in] unsigned short y_max, [in]unsigned __int64 time, [in]unsigned long interpolate_method, [in, out] SAFEARRAY(IWXData)*wx, [in, out] SAFEARRAY(IFWIData)*ifwi, [in, out] SAFEARRAY(DFWIData)*dfwi) |
HRESULT | GetAttributeDataArray ([in] __int64 layerThread, [in]unsigned short x_min, [in]unsigned short y_min, [in]unsigned short x_max, [in]unsigned short y_max, [in] unsigned __int64 time, [in] unsigned short option, [in, out] SAFEARRAY(VARIANT)*attribute) |
HRESULT | GetEventTime ([in] __int64 layerThread, [in] unsigned long flags, [in] unsigned __int64 from_time, [out, retval] unsigned __int64 *next_event) |
HRESULT | PreCalculationEvent ([in] __int64 layerThread, [in] unsigned __int64 time, [in] unsigned long mode) |
HRESULT | PostCalculationEvent ([in] __int64 layerThread, [in] unsigned __int64 time, [in] unsigned long mode) |
HRESULT | GetGridEngine ([in] __int64 layerThread, [out, retval] ICWFGM_GridEngine **pVal) |
HRESULT | PutGridEngine ([in] __int64 layerThread, [in] ICWFGM_GridEngine *newVal) |
Properties | |
ICWFGM_LayerManager | LayerManager [get, set] |
VARIANT | UserData [get, set] |
Interface ICWFGM Grid Engine.
Grid data is provided to the simulation engine by the client application. The simulation engine defines the interface it will use to obtain the grid data (via this interface). The simulation engine is not concerned with the kind of object that implements this interface, or the implementation of the object. It may represent the original CWFGM grid data, a CWFGM grid filter object or some other object a programmer has built to access a specialized data set.
The simulation engine does not define any object that implements this interface. The simulation engine only defines the interface. Objects that implement this interface should import this interface definition. The object implementing this interface is to be handled entirely by the client application (such as CWFGM). Methods to import grid data or manage grid filters are not found on this COM interface, as the simulation engine has no need for these methods. This design takes advantage of object-oriented methodologies to simplify both the design of the simulation engine, and the integration of the simulation engine into another application. For example, to provide data from a G.I.S. directly to the simulation engine, the programmer only needs to define an object that implements this interface and communicates with the G.I.S. A variety of objects that implement this interface already exist.
There are no methods on the simulation engine interface to add or remove FBP fuel types. This is because the simulation engine is not concerned with managing fuel types, or the look-up tables used to associate a fuel type with a grid map entry. These tasks are left entirely to the client application. This works because the interface method GetFuelData()only returns handles to FBP fuel types after the client has finished resolving its own look-up tables and grid filters. Similarly, there are no methods on the simulation engine interface to add or remove firebreaks or firelines. Firebreaks and firelines are represented by objects supporting the FBP fuel type interface. The object implementing the Grid COM interface locates firebreaks, etc. on the fuel array and returns the correct handles via the GetFuelData() method. Any temporal aspect of these objects is the responsibility of the client application. The IDL of the grid object required by the simulation engine is given below.
ICWFGM_GridEngine::GetAttribute | ( | [in] __int64 | layerThread, |
[in] unsigned short | option, | ||
[out,retval] VARIANT * | value | ||
) |
Polymorphic. This method returns a specified value obtained from the projection file or grid data. These values are useful for importing vector data, locating the plot on the planet, etc. and are not specific to any particular location within the grid.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
option | The attribute of interest. |
value | Location for the retrieved value to be placed. |
ICWFGM_GridEngine::GetAttributeData | ( | [in] __int64 | layerThread, |
[in] unsigned short | x, | ||
[in] unsigned short | y, | ||
[in] unsigned __int64 | time, | ||
[in] unsigned short | option, | ||
[out,retval] VARIANT * | attribute | ||
) |
Polymorphic. Given a (X,Y) location in the the grid and a GMT time since January 1st, 1600, returns an attribute value keyed on 'option'. Note that only specific objects implementing this interface can be expected to return valid values from this function call.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
x | X grid location. |
y | Y grid location. |
time | A GMT time provided as seconds since January 1st, 1600. |
option | Option information. Currently expected values are:
|
attribute | Attirbute data |
ICWFGM_GridEngine::GetAttributeDataArray | ( | [in] __int64 | layerThread, |
[in] unsigned short | x_min, | ||
[in] unsigned short | y_min, | ||
[in] unsigned short | x_max, | ||
[in] unsigned short | y_max, | ||
[in] unsigned __int64 | time, | ||
[in] unsigned short | option, | ||
[in,out] SAFEARRAY(VARIANT)* | attribute | ||
) |
Polymorphic. Given a ('X_min','Y_min')->('X_max','Y_max') range of locations (inclusive) in the grid and a GMT time since January 1st, 1600, returns an attribute value keyed on 'option'. Note that only specific objects implementing this interface can be expected to return valid values from this function call. The 2D array is expected to begin at (0,0) and contain enough room for both dimensions of requested data.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
x_min | Minimum value (inclusive) on x-axis. |
y_min | Minimum value (inclusive) on y-axis. |
x_max | Maximum value (inclusive) on x-axis. |
y_max | Maximum value (inclusive) on y-axis. |
time | A GMT time provided as seconds since January 1st, 1600. |
option | Option information. Currently expected values are:
|
attribute | Data array |
ICWFGM_GridEngine::GetDimensions | ( | [in] __int64 | layerThread, |
[out] unsigned short * | x_dim, | ||
[out] unsigned short * | y_dim | ||
) |
This method assigns 'x_dim' and 'y_dim' to the size of the grid, in grid units.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
x_dim | x dimension of the grid. |
y_dim | y dimension of the grid. |
ICWFGM_GridEngine::GetElevationData | ( | [in] __int64 | layerThread, |
[in] unsigned short | x, | ||
[in] unsigned short | y, | ||
[in] short | allow_defaults_returned, | ||
[out] double * | elevation, | ||
[out] double * | slope_factor, | ||
[out] double * | slope_azimuth | ||
) |
Given a (X,Y) location in the grid, returns elevation information.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
x | x grid location. |
y | y grid location. |
allow_defaults_returned | Flag for allowing defaults to be returned |
elevation | Elevation (m) of the requested location. |
slope_factor | Percentage ground slope specified as a decimal value (0 - 1) |
slope_azimuth | Direction of up-slope, Cartesian radians. |
ICWFGM_GridEngine::GetElevationDataArray | ( | [in] __int64 | layerThread, |
[in] unsigned short | x_min, | ||
[in] unsigned short | y_min, | ||
[in] unsigned short | x_max, | ||
[in] unsigned short | y_max, | ||
[in] short | allow_defaults_returned, | ||
[in,out] SAFEARRAY(double)* | elevation, | ||
[in,out] SAFEARRAY(double)* | slope_factor, | ||
[in,out] SAFEARRAY(double)* | slope_azimuth | ||
) |
Given a ('X_min','Y_min')->('X_max','Y_max') range of locations (inclusive) in the grid, this method fills the provided arrays with elevation data. This routine uses the array provided by the client rather than returning allocated memory in case the client wants to make successive requests - this will avoid repeated memory allocations and de-allocations. The 2D array is expected to begin at (0,0) and contain enough room for both dimensions of requested data.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
x_min | Minimum value (inclusive) on x-axis. |
y_min | Minimum value (inclusive) on y-axis. |
x_max | Maximum value (inclusive) on x-axis. |
y_max | Maximum value (inclusive) on y-axis. |
allow_defaults_returned | Flag for allowing defaults to be returned |
elevation | Array of elevations (to fill in). |
slope_factor | Array of slope factors (to fill in). |
slope_azimuth | Array of slope azimuths (to fill in). |
ICWFGM_GridEngine::GetEventTime | ( | [in] __int64 | layerThread, |
[in] unsigned long | flags, | ||
[in] unsigned __int64 | from_time, | ||
[out,retval] unsigned __int64 * | next_event | ||
) |
This method allows the simulation engine to scan forward or back (based on flags) from a given time for the next time-based event. This is important for the event-driven nature of the simulation.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
flags | Event related flags. Currently valid values are:
|
from_time | A GMT time provided as seconds since January 1st, 1600. |
next_event | A GMT time provided as seconds since January 1st, 1600, representing the time for the next event, based on 'flags'. |
ICWFGM_GridEngine::GetFuelData | ( | [in] __int64 | layerThread, |
[in] unsigned short | _x, | ||
[in] unsigned short | _y, | ||
[in] unsigned __int64 | time, | ||
[out,retval] ICWFGM_Fuel ** | fuel | ||
) |
Given a (X,Y) location in the grid and a GMT time provided as seconds since January 1st, 1600), returns a handle to a CWFGM Fuel.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
_x | X grid location. |
_y | Y grid location. |
time | A GMT time provided as seconds since January 1st, 1600. |
fuel | A CWGFM fuel. |
ICWFGM_GridEngine::GetFuelDataArray | ( | [in] __int64 | layerThread, |
[in] unsigned short | _x_min, | ||
[in] unsigned short | _y_min, | ||
[in] unsigned short | _x_max, | ||
[in] unsigned short | _y_max, | ||
[in] unsigned __int64 | time, | ||
[in,out] SAFEARRAY(ICWFGM_Fuel *)* | fuel | ||
) |
Given a ('X_min','Y_min')->('X_max','Y_max') range of locations (inclusive) in the grid, and a GMT time (seconds since January 1st, 1600), this method fills the provided array with handles to a CWFGM Fuels. This routine uses the array provided by the client rather than returning allocated memory in case the client wants to make successive requests - this will avoid repeated memory allocations and deallocations. The 2D array is expected to begin at (0,0) and contain enough room for both dimensions of requested data. When using this routine to retrieve 2000 points at a time, it is approximately 75% faster than successive GetFuelData() calls.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
_x_min | Minimum value (inclusive) on x-axis. |
_y_min | Minimum value (inclusive) on y-axis. |
_x_max | Maximum value (inclusive) on x-axis. |
_y_max | Maximum value (inclusive) on y-axis. |
time | A GMT time provided as seconds since January 1st, 1600. |
fuel | Array of CWFGM fuels (to fill in). |
ICWFGM_GridEngine::GetFuelIndexData | ( | [in] __int64 | layerThread, |
[in] unsigned short | x, | ||
[in] unsigned short | y, | ||
[in] unsigned __int64 | time, | ||
[out,retval] unsigned char * | fuel_index | ||
) |
Given a (X,Y) location in the grid and a GMT time since January 1st, 1600, returns an internal index of a CWFGM Fuel. The fuel can then be determined by a call to the attached FuelMap object. This method is not used by the simulation engine, but instead is intended for filters that need core data from the grid.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
x | X grid location. |
y | Y grid location. |
time | A GMT time provided as seconds since January 1st, 1600. |
fuel_index | Index of a CWFGM fuel. |
ICWFGM_GridEngine::GetFuelIndexDataArray | ( | [in] __int64 | layerThread, |
[in] unsigned short | _x_min, | ||
[in] unsigned short | _y_min, | ||
[in] unsigned short | _x_max, | ||
[in] unsigned short | _y_max, | ||
[in] unsigned __int64 | time, | ||
[in,out] SAFEARRAY(unsigned char)* | fuel_index | ||
) |
Given a ('X_min','Y_min')->('X_max','Y_max') range of locations (inclusive) in the grid, and a GMT time (count of seconds since January 1st, 1600), this method fills the provided array with internal indices of CWFGM Fuels. The fuels can then be determined by calls to the attached FuelMap object. This method is not used by the simulation engine, but instead is intended for filters that need core data from the grid. This routine uses the array provided by the client rather than returning allocated memory in case the client wants to make successive requests - this will avoid repeated memory allocations and deallocations. The 2D array is expected to begin at (0,0) and contain enough room for both dimensions of requested data. When using this routine to retrieve 2000 points at a time, it is approximately 75% faster than successive GetFuelData() calls.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
_x_min | Minimum value (inclusive) on x-axis. |
_y_min | Minimum value (inclusive) on y-axis. |
_x_max | Maximum value (inclusive) on x-axis. |
_y_max | Maximum value (inclusive) on y-axis. |
time | A GMT time provided as seconds since January 1st, 1600. |
fuel_index | Array of indices of CWFGM fuels (to fill in). |
ICWFGM_GridEngine::GetGridEngine | ( | [in] __int64 | layerThread, |
[out, retval] ICWFGM_GridEngine ** | pVal | ||
) |
This method retrieves the next lower GIS layer for layerThread, used to determine the stacking and order of objects associated to a scenario.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
pVal | Pointer to Grid Engine |
ICWFGM_GridEngine::GetWeatherData | ( | [in] __int64 | layerThread, |
[in] unsigned short | x, | ||
[in] unsigned short | y, | ||
[in] unsigned __int64 | time, | ||
[in] unsigned long | interpolate_method, | ||
[out] IWXData * | wx, | ||
[out] IFWIData * | ifwi, | ||
[out] DFWIData * | dfwi | ||
) |
Given a (X,Y) location in the grid, returns weather information. Note that only specific objects implementing this interface can be expected to return valid values from this function call.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
x | x grid location. |
y | y grid location. |
time | A GMT time provided as seconds since January 1st, 1600. |
interpolate_method | Method of interpolation. |
wx | Weather information. |
ifwi | IFWI Information. |
dfwi | DFWI Information. |
ICWFGM_GridEngine::GetWeatherDataArray | ( | [in] __int64 | layerThread, |
[in] unsigned short | x_min, | ||
[in] unsigned short | y_min, | ||
[in] unsigned short | x_max, | ||
[in] unsigned short | y_max, | ||
[in] unsigned __int64 | time, | ||
[in] unsigned long | interpolate_method, | ||
[in,out] SAFEARRAY(IWXData)* | wx, | ||
[in,out] SAFEARRAY(IFWIData)* | ifwi, | ||
[in,out] SAFEARRAY(DFWIData)* | dfwi | ||
) |
Given a ('X_min','Y_min')->('X_max','Y_max') range of locations (inclusive) in the grid, this method fills the provided arrays with weather data. This routine uses the array provided by the client rather than returning allocated memory in case the client wants to make successive requests - this will avoid repeated memory allocations and de-allocations. The 2D arrays are expected to begin at (0,0) and contain enough room for both dimensions of requested data.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
x_min | Minimum value (inclusive) on x-axis. |
y_min | Minimum value (inclusive) on y-axis. |
x_max | Maximum value (inclusive) on x-axis. |
y_max | Maximum value (inclusive) on y-axis. |
time | A GMT time provided as seconds since January 1st, 1600. |
interpolate_method | Method of interpolation. |
wx | Array of Weather information. |
ifwi | Array of Instantaneous FWI codes. |
dfwi | Array of Daily FWI codes. |
ICWFGM_GridEngine::MT_Lock | ( | [in] __int64 | layerThread, |
[in] unsigned short | exclusive, | ||
[in] unsigned short | obtain | ||
) |
Changes the state of the object with respect to access rights. When the object is used by an active simulation, it must not be modified. When the object is somehow modified, it must be done so in an atomic action to prevent concerns with arising from multithreading. Note that these locks are primarily needed to ensure that data contributing during a simulation is not modified while the simulation is executing.
All routines in the ICWFGM_GridEngine interface are necessarily NOT multithreading safe (for performance) but other interfaces for a given COM object implementing this interface must be by specification.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
exclusive | TRUE if the requester wants a write lock, false for read/shared access |
obtain | TRUE to obtain the lock, FALSE to release the lock. If this is FALSE, then the 'exclusive' parameter must match the initial call used to obtain the lock. |
ICWFGM_GridEngine::PostCalculationEvent | ( | [in] __int64 | layerThread, |
[in] unsigned __int64 | time, | ||
[in] unsigned long | mode | ||
) |
This method is invoked after all calculations are performed in the simulation, and after calculations are performed on a given simulation time step. It's intended to perform post-calculation clean-up, etc.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
time | A GMT time provided as seconds since January 1st, 1600. |
mode | Calculation mode: 0 represents start of simulation, 1 represents start of a specific time step |
ICWFGM_GridEngine::PreCalculationEvent | ( | [in] __int64 | layerThread, |
[in] unsigned __int64 | time, | ||
[in] unsigned long | mode | ||
) |
This method is invoked before any calculations are performed in the simulation, and before calculations are performed on a given simulation time step. It's intended to perform pre-calculation caching events, etc.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
time | A GMT time provided as seconds since January 1st, 1600. |
mode | Calculation mode: 0 represents start of simulation, 1 represents start of a specific time step |
ICWFGM_GridEngine::PutGridEngine | ( | [in] __int64 | layerThread, |
[in] ICWFGM_GridEngine * | newVal | ||
) |
This method sets the next lower GIS layer for layerThread, used to determine the stacking and order of objects associated to a scenario.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
newVal | Pointer to Grid Engine |
ICWFGM_GridEngine::Valid | ( | [in] __int64 | layerThread, |
[in] unsigned __int64 | start_time, | ||
[in] __int64 | duration, | ||
[in] unsigned long | option, | ||
[in,out] SAFEARRAY(unsigned short)* | application_count | ||
) |
This method returns whether this grid object has been initialized,and whether it contains all data necessary for a simulation (including weather data) for the simulation time identified by start_time and duration. If start_time and duration are both 0, then this method only returns whether the object is initialized. The invoked object is allowed to perform a variety of other operations and method calls to initialize and validate, and possibly cache data.
layerThread | Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers. |
start_time | Start time of the simulation. A GMT time provided as seconds since January 1st, 1600. |
duration | Duration of the simulation, in seconds. |
option | Determines type of Valid request. |
application_count | Optional (dependent on option). Array of counts for how often a particular type of grid occurs in the set of ICWFGM_GridEngine objects associated with a scenario. |
|
getsetproperty |
This property is must be set before any calls to GetGridEngine or PutGridEngine. Additionally, this property should be considered write-once. This value should be set to the ICWFGM_LayerManager object which any layerThread assigned to this object will have been allocated from.
pVal | value of LayerManager |
newVal | value for LayerManager |
|
getsetproperty |
This property is unused by this object, and is available for exclusive use by the client code. It is a VARIANT value to ensure that the client code can store a pointer value (if it chooses) for use in manual subclassing this object. This value is not loaded or saved during serialization operations, and it is the responsibility of the client code to manage any value or object stored here. Access to this property is not thread-safe.
pVal | value of UserData |
newVal | replacement value for UserData |