All Classes Functions Variables Properties
List of all members | Public Member Functions | Properties
ICWFGM_VectorEngine Class Reference

Interface ICWFGM VectorEngine. More...

import "GridCom.idl";

Collaboration diagram for ICWFGM_VectorEngine:
Collaboration graph

Public Member Functions

HRESULT MT_Lock ([in] unsigned short exclusive, [in] unsigned short obtain)
 
HRESULT Valid ([in]unsigned __int64 start_time, [in]__int64 duration)
 
HRESULT GetFireBreakRange ([in]unsigned long index, [in]unsigned __int64 time, [out]double *x_min, [out]double *y_min, [out]double *x_max, [out]double *y_max)
 
HRESULT GetFireBreakCount ([in]unsigned __int64 time, [out, retval]unsigned long *count)
 
HRESULT GetFireBreakSetCount ([in]unsigned __int64 time, [in]unsigned long index, [out, retval]unsigned long *count)
 
HRESULT GetFireBreakSize ([in]unsigned long index, [in]unsigned long sub_index, [in]unsigned __int64 time, [out, retval]unsigned long *size)
 
HRESULT GetFireBreak ([in]unsigned long index, [in]unsigned long sub_index, [in]unsigned __int64 time, [in, out]unsigned long *size, [in, out] SAFEARRAY(double)*xy_pairs)
 
HRESULT GetAttribute ([in]unsigned short option, [out, retval]VARIANT *value)
 
HRESULT SetAttribute ([in]unsigned short option, [in]VARIANT value)
 
HRESULT GetEventTime ([in] unsigned long flags, [in] unsigned __int64 from_time, [out, retval] unsigned __int64 *next_event)
 
HRESULT PreCalculationEvent ([in] unsigned __int64 time, [in] unsigned long mode)
 
HRESULT PostCalculationEvent ([in] unsigned __int64 time, [in] unsigned long mode)
 

Properties

ICWFGM_GridEngine GridEngine [get, set]
 
VARIANT UserData [get, set]
 

Detailed Description

Interface ICWFGM VectorEngine.

Vector data is provided to the simulation engine by the client application. The simulation engine defines the interface it will use to obtain the vector fuel break data. 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 GIS vector-based data, a user-defined static vector fuelbreak, or a user-controlled break that changes over time, 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 vector data or manage vector 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. Unlike ICWFGM_GridEngine interface objects that must be chained (layered) together to attain the appropriate grid layer for the simulation, objects implementing this interface don't replace or override other vector object data, they are only combined. As such, the order is unimportant so there are no methods to chain ICWFGM_VectorEngine objects together here. The simulation's scenario object can use many ICWFGM_VectorEngine objects simultaneously. At this time, the simulation engine assumes that fuel breaks defined by this interface have 100% effect on the fire; the fire will not escape the confines of a vector fuel break.

The IDL of the vector object required by the simulation engine is given below. Program developers are encouraged to obtain the latest electronic copy of the programming tools from the resources listed at the end of this document.

Member Function Documentation

ICWFGM_VectorEngine::GetAttribute ( [in] unsigned short  option,
[out, retval] VARIANT *  value 
)

Polymorphic. This routine retrieves an attribute/option value given the attribute/option index.

Parameters
optionAttribute of interest.
valueReturn value for the attribute/option index.
ICWFGM_VectorEngine::GetEventTime ( [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.

Parameters
flagsEvent related flags. Currently valid values are:
  • CWFGM_GETEVENTTIME_FLAG_SEARCH_FORWARD search forward in time
  • CWFGM_GETEVENTTIME_FLAG_SEARCH_BACKWARD search backwards in time
  • CWFGM_GETEVENTTIME_QUERY_PRIMARY_WX_STREAM only the primary weather stream may respond
  • CWFGM_GETEVENTTIME_QUERY_ANY_WX_STREAM only weather streams may respond
All other values are reserved for future use.
from_timeA GMT time provided as seconds since January 1st, 1600.
next_eventA GMT time provided as seconds since January 1st, 1600, representing the time for the next event, based on 'flags'.
ICWFGM_VectorEngine::GetFireBreak ( [in] unsigned long  index,
[in] unsigned long  sub_index,
[in] unsigned __int64  time,
[in,out] unsigned long *  size,
[in,out] SAFEARRAY(double)*  xy_pairs 
)

This method returns the vertices defining specified vector break (index) at the specified time. The provided array must be large enough to hold all returned value. 'size' is adjusted as necessary to return the number of array entries used. X, Y values are scaled to the grid coordinate resolution.

Parameters
indexIndex of Fire Break to retrieve.
sub_indexSub-Index of Fire Break to retrieve.
timeA GMT time provided as seconds since January 1st, 1600.
sizeReturns number of elements filled into provided array.
xy_pairs2D Array of coordinates

This method returns the vertices defining specified vector break (index) at the specified time. The provided array must be large enough to hold all returned value. 'size' is adjusted as necessary to return the number of array entries used. X, Y values are scaled to the grid coordinate resolution.

Parameters
indexIdentifies a firebreak.
sub_indexIdentifies sub parts of a firebreak.
timeA GMT time provided as seconds since January 1st, 1600.
sizeNumber of array entries used. (When the method is called, this value should contain the size of the available array to fill in.)
xy_pairs2D Array of coordinates
ICWFGM_VectorEngine::GetFireBreakCount ( [in] unsigned __int64  time,
[out, retval] unsigned long *  count 
)

This method returns the number of vector breaks represented in this object for the specified time. Each vector firebreak is contiguous.

Parameters
timeA GMT time provided as seconds since January 1st, 1600.
countNumber of vector breaks.
ICWFGM_VectorEngine::GetFireBreakRange ( [in] unsigned long  index,
[in] unsigned __int64  time,
[out] double *  x_min,
[out] double *  y_min,
[out] double *  x_max,
[out] double *  y_max 
)

This method returns the bounding box for a particular fuel break vector from this object at a given time, or, if index is –1, then the bounding box for all vectors is returned.

Parameters
indexIdentifies a fire break.
timeA GMT time provided as seconds since January 1st, 1600.
x_minMinimum X value for this specific fire break.
y_minMinimum Y value for this specific fire break.
x_maxMaximum X value for this specific fire break.
y_maxMaximum Y value for this specific fire break.
ICWFGM_VectorEngine::GetFireBreakSetCount ( [in] unsigned __int64  time,
[in] unsigned long  index,
[out, retval] unsigned long *  count 
)

This method returns the number of vector breaks represented in this object for the specified time. Each vector firebreak is contiguous.

Parameters
timeA GMT time provided as seconds since January 1st, 1600.
countNumber of vector breaks.
indexIndex of the firebreak.
ICWFGM_VectorEngine::GetFireBreakSize ( [in] unsigned long  index,
[in] unsigned long  sub_index,
[in] unsigned __int64  time,
[out, retval] unsigned long *  size 
)

This method returns the number of indices of the specified vector break at the specified time. Or, if index is -1, then the size of the largest polyline / polygon for all indices, sub-indices is return.

Parameters
indexIdentifies a fire break.
sub_indexIdentifies sub pieces of a fire break.
timeA GMT time provided as seconds since January 1st, 1600.
sizeNumber of indices.
ICWFGM_VectorEngine::MT_Lock ( [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_VectorEngine interface are necessarily NOT multithreading safe (for performance) but other interfaces for a given COM object implementing this interface must be by specification.

Parameters
exclusiveTRUE if the requester wants a write lock, false for read/shared access
obtainTRUE 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_VectorEngine::PostCalculationEvent ( [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.

Parameters
timeA GMT time provided as seconds since January 1st, 1600.
modeCalculation mode: 0 represents start of simulation, 1 represents start of a specific time step
ICWFGM_VectorEngine::PreCalculationEvent ( [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.

Parameters
timeA GMT time provided as seconds since January 1st, 1600.
modeCalculation mode: 0 represents start of simulation, 1 represents start of a specific time step
ICWFGM_VectorEngine::SetAttribute ( [in] unsigned short  option,
[in] VARIANT  value 
)

Sets the value for the attribute denoted by "option".

Parameters
optionThe attribute to change.
valueThe value to set the attribute to.
ICWFGM_VectorEngine::Valid ( [in] unsigned __int64  start_time,
[in] __int64  duration 
)

This method returns whether this vector object has been initialized,and whether it contains all data necessary for a simulation 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.

Parameters
start_timeStart time of the simulation. A GMT time provided as seconds since January 1st, 1600.
durationDuration of the simulation, in seconds.

Property Documentation

Property ICWFGM_VectorEngine::GridEngine
getsetproperty

Sets or retrieves the object exposing the GridEngine interface that this VectorEngine object may refer to, to use for tasks such as bounds clipping, etc.

Parameters
pValValue of GridEngine.
newValReplacement value for GridEngine.
Property ICWFGM_VectorEngine::UserData
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.

Parameters
pValValue of UserData.
newValReplacement value for UserData.