Read/write FBP fuel type. More...

#include <CWFGM_Fuel_Shared.h>

Collaboration diagram for CCWFGM_Fuel:

Public Member Functions
STDMETHOD()	MT_Lock (USHORT exclusive, USHORT obtain)

STDMETHOD()	Clone (ICWFGM_Fuel **newFuel)

STDMETHOD()	FMC (double lat, double lon, double elev, USHORT day, double *fmc)

STDMETHOD()	CalculateROSValues (double GS, double SAZ, double WS, double WAZ, double BUI, double FMC, double FFMC, double fF, ULONGLONG t, ULONGLONG ffmc_t, short flag, double rss, double roseq, double ros, double frss, double froseq, double fros, double brss, double broseq, double bros, double wsv, double *raz)

STDMETHOD()	CalculateFCValues (double FFMC, double BUI, double FMC, double RSS, double ROS, short flag, double cfb, double cfc, double rso, double csi, double sfc, double tfc, double *fi)

STDMETHOD()	CalculateStatistics (double ROS, double FROS, double BROS, double CFB, ULONGLONG time, short flag, double area, double perimeter)

STDMETHOD()	CalculateDistances (double ROS, double FROS, double BROS, double CFB, ULONGLONG time, short flag, double dhead, double dflank, double *dback)

STDMETHOD()	ISF (double RSF, double SF, double ISZ, short flag, double *isfValue)

STDMETHOD()	SFC (double FFMC, double BUI, short flag, double *sfc)

STDMETHOD()	RSI (double FFMC, double BUI, double FMC, double ISI, short flag, double *rsi)

STDMETHOD()	get_UserData (VARIANT *pVal)

STDMETHOD()	put_UserData (VARIANT newVal)

STDMETHOD()	get_Name (BSTR *pVal)

STDMETHOD()	put_Name (const BSTR newVal)

STDMETHOD()	get_C2 (ICWFGM_Fuel **pVal)

STDMETHOD()	put_C2 (ICWFGM_Fuel *newVal)

STDMETHOD()	get_D1 (ICWFGM_Fuel **pVal)

STDMETHOD()	put_D1 (ICWFGM_Fuel *newVal)

STDMETHOD()	IsConiferFuelType (VARIANT_BOOL *retbool)

STDMETHOD()	IsDeciduousFuelType (VARIANT_BOOL *retbool)

STDMETHOD()	IsMixedFuelType (VARIANT_BOOL *retbool)

STDMETHOD()	IsGrassFuelType (VARIANT_BOOL *retbool)

STDMETHOD()	IsC6FuelType (VARIANT_BOOL *retbool)

STDMETHOD()	IsSlashFuelType (VARIANT_BOOL *retbool)

STDMETHOD()	IsMixedDeadFirFuelType (VARIANT_BOOL *retbool)

STDMETHOD()	IsNonFuel (VARIANT_BOOL *retbool)

STDMETHOD()	SetDefaultCLSID (CLSID *clsID)

STDMETHOD()	GetDefaultCLSID (CLSID *clsID)

STDMETHOD()	GetAttribute (USHORT option, VARIANT *value)

STDMETHOD()	SetAttribute (USHORT option, VARIANT value)

STDMETHOD()	GetEquation (USHORT equationKey, USHORT *equation)

STDMETHOD()	SetEquation (USHORT equationKey, USHORT equation)

STDMETHOD()	get_CustomEquation_Accel (ICWFGM_AccelAttribute **pVal)

STDMETHOD()	put_CustomEquation_Accel (ICWFGM_AccelAttribute *newVal)

STDMETHOD()	get_CustomEquation_FMC (ICWFGM_FMCAttribute **pVal)

STDMETHOD()	put_CustomEquation_FMC (ICWFGM_FMCAttribute *newVal)

STDMETHOD()	get_CustomEquation_SFC (ICWFGM_SFCAttribute **pVal)

STDMETHOD()	put_CustomEquation_SFC (ICWFGM_SFCAttribute *newVal)

STDMETHOD()	get_CustomEquation_TFC (ICWFGM_TFCAttribute **pVal)

STDMETHOD()	put_CustomEquation_TFC (ICWFGM_TFCAttribute *newVal)

STDMETHOD()	get_CustomEquation_CFB (ICWFGM_CFBAttribute **pVal)

STDMETHOD()	put_CustomEquation_CFB (ICWFGM_CFBAttribute *newVal)

STDMETHOD()	get_CustomEquation_RSI (ICWFGM_RSIAttribute **pVal)

STDMETHOD()	put_CustomEquation_RSI (ICWFGM_RSIAttribute *newVal)

STDMETHOD()	get_CustomEquation_ISF (ICWFGM_ISFAttribute **pVal)

STDMETHOD()	put_CustomEquation_ISF (ICWFGM_ISFAttribute *newVal)

STDMETHOD()	get_CustomEquation_LB (ICWFGM_LBAttribute **pVal)

STDMETHOD()	put_CustomEquation_LB (ICWFGM_LBAttribute *newVal)

Public Member Functions inherited from ICWFGM_FBPFuel
HRESULT	SetDefaultCLSID ([in] CLSID *clsId)

HRESULT	GetEquation ([in] unsigned short equationKey, [out, retval] unsigned short *equation)

HRESULT	SetEquation ([in] unsigned short equationKey, [in] unsigned short equation)

Public Member Functions inherited from ICWFGM_Fuel
HRESULT	MT_Lock ([in] unsigned short exclusive, [in] unsigned short obtain)

HRESULT	Clone ([out]ICWFGM_Fuel **newFuel)

HRESULT	FMC ([in]double latitude, [in]double longitude, [in]double elev, [in]unsigned short day, [out, retval]double *fmc)

HRESULT	CalculateROSValues ([in]double GS, [in]double SAZ, [in]double WS, [in]double WAZ, [in]double BUI, [in]double FMC, [in]double FFMC, [in]double fF, [in]ULONGLONG time, [in]ULONGLONG ffmc_time, [in] short flag, [out]double rss, [out]double roseq, [out]double ros, [out]double frss, [out]double froseq, [out]double fros, [out]double brss, [out]double broseq, [out]double bros, [out]double wsv, [out]double *raz)

HRESULT	CalculateFCValues ([in]double FFMC, [in]double BUI, [in]double FMC, [in]double RSS, [in]double ROS, [in]short flag, [out]double cfb, [out]double cfc, [out]double rso, [out]double csi, [out]double sfc, [out]double tfc, [out]double *fi)

HRESULT	CalculateStatistics ([in]double ROS, [in]double FROS, [in]double BROS, [in]double CFB, [in]ULONGLONG time, [in]short flag, [out]double area, [out]double perimeter)

HRESULT	CalculateDistances ([in]double ROS, [in]double FROS, [in]double BROS, [in]double CFB, [in]ULONGLONG time, [in]short flag, [out]double dhead, [out]double dflank, [out]double *dback)

HRESULT	ISF ([in]double RSF, [in]double SF, [in]double ISZ, [in]short flag,[out]double *isfValue)

HRESULT	SFC ([in] double FFMC, [in] double BUI, [in] short flag, [out, retval] double *sfc)

HRESULT	RSI ([in]double FFMC, [in]double BUI, [in]double FMC, [in]double ISI, [in] short flag, [out, retval]double *rsi)

HRESULT	IsConiferFuelType ([out, retval] VARIANT_BOOL *retbool)

HRESULT	IsDeciduousFuelType ([out, retval] VARIANT_BOOL *retbool)

HRESULT	IsMixedFuelType ([out, retval] VARIANT_BOOL *retbool)

HRESULT	IsGrassFuelType ([out, retval] VARIANT_BOOL *retbool)

HRESULT	IsC6FuelType ([out, retval] VARIANT_BOOL *retbool)

HRESULT	IsMixedDeadFirFuelType ([out, retval]VARIANT_BOOL *retbool)

HRESULT	IsSlashFuelType ([out, retval]VARIANT_BOOL *retbool)

HRESULT	IsNonFuel ([out, retval] VARIANT_BOOL *retbool)

HRESULT	GetDefaultCLSID ([out, retval] CLSID *clsId)

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

HRESULT	SetAttribute ([in]unsigned short option, [in]VARIANT value)

Additional Inherited Members
Properties inherited from ICWFGM_FBPFuel
BSTR	Name `[set]`

ICWFGM_Fuel	C2 `[get, set]`

ICWFGM_Fuel	D1 `[get, set]`

ICWFGM_AccelAttribute	CustomEquation_Accel `[get, set]`

ICWFGM_FMCAttribute	CustomEquation_FMC `[get, set]`

ICWFGM_SFCAttribute	CustomEquation_SFC `[get, set]`

ICWFGM_TFCAttribute	CustomEquation_TFC `[get, set]`

ICWFGM_CFBAttribute	CustomEquation_CFB `[get, set]`

ICWFGM_RSIAttribute	CustomEquation_RSI `[get, set]`

ICWFGM_ISFAttribute	CustomEquation_ISF `[get, set]`

ICWFGM_LBAttribute	CustomEquation_LB `[get, set]`

Properties inherited from ICWFGM_Fuel
BSTR	Name `[get]`

VARIANT	UserData `[get, set]`

Detailed Description

Read/write FBP fuel type.

CCWFGM_Fuel implements both ICWFGM_Fuel and ICWFGM_FBPFuel interfaces. This fuel type is read/write and is normally created by cloning a read-only template fuel type, then applying necesssary and appropriate modifications.

Member Function Documentation

STDMETHOD() CCWFGM_Fuel::CalculateDistances	(	double	ROS,
		double	FROS,
		double	BROS,
		double	CFB,
		ULONGLONG	time,
		short	flag,
		double *	dhead,
		double *	dflank,
		double *	dback
	)

Calculates spread distances of the theoretical ellipse defined by ROS, FROS, BROS.

Parameters

ROS	Equilibrium rate of spread (metres per minute).
FROS	Equilibrium flank rate of spread (metres per minute).
BROS	Equilibrium back rate of spread (metres per minute).
CFB	Crown fraction burned.
time	Time since fire start, important if acceleration is turned on.
flag	A combination of `CWFGM_SCENARIO_OPTION_ACCEL` Boolean. If TRUE, then acceleration is applied to various output statistics in the FBP standard. This value should only applicable to point ignitions. If FALSE, then the fire is assumed to be always at equilibrium. `CWFGM_SCENARIO_OPTION_BUI` Boolean. If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard. `CWFGM_SCENARIO_OPTION_TOPOGRAPHY` Boolean. If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. This setting also affects the slope component in Dr. Richards' 3D equations. `CWFGM_SCENARIO_OPTION_GREENUP` Boolean. Specific FBP fuel types use different equations during green-up. This flag determines whether to use green-up equations or not. `CWFGM_SCENARIO_OPTION_WIND` Boolean. If FALSE, then the wind component to calculating the WSV statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. bit flags, defined in FireEngine_Ext.h. For consistency of outputs, these flags should match those provided to determine the ROS values.
dhead	Calculated value, head fire spread distance.
dflank	Calculated value, flank fire spread distance.
dback	Calculated value, back fire spread distance.

See Also: ICWFGM_Fuel::CalculateDistances

Return values

E_POINTER	the address provided is invalid
S_OK	Successful
E_INVALIDARG	Invalid inputs have caused an error

STDMETHOD() CCWFGM_Fuel::CalculateFCValues	(	double	FFMC,
		double	BUI,
		double	FMC,
		double	RSS,
		double	ROS,
		short	flag,
		double *	cfb,
		double *	cfc,
		double *	rso,
		double *	csi,
		double *	sfc,
		double *	tfc,
		double *	fi
	)

Given several input parameters, calculates FC (fuel consumption) values. The specific set of equations used to calculate FC values is determined by the fuel type and/or any modifications which have been applied.

Automatic caching of previously calculated values is performed for efficiency.
\param FFMC Fine fuel moister code (FWI output)
\param BUI  Buildup index (FWI output)
\param FMC  Foliar moisture code (FBP output) (0-1)
\param RSS  (metres per minute)
\param ROS  Rate of spread (metres per minute)
\param flag A combination of
            <ul>
            <li><code>CWFGM_SCENARIO_OPTION_ACCEL</code>  Boolean.  If TRUE, then acceleration is applied to various output statistics in the FBP standard.  This value should only applicable to point ignitions.  If FALSE, then the fire is assumed to be always at equilibrium.
            <li><code>CWFGM_SCENARIO_OPTION_BUI</code>  Boolean.  If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard.
            <li><code>CWFGM_SCENARIO_OPTION_TOPOGRAPHY</code>  Boolean.  If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0.  If TRUE, then the wind speed is used as provided.  This setting also affects the slope component in Dr. Richards' 3D equations.
            <li><code>CWFGM_SCENARIO_OPTION_GREENUP</code>  Boolean.  Specific FBP fuel types use different equations during green-up.  This flag determines whether to use green-up equations or not.
            <li><code>CWFGM_SCENARIO_OPTION_WIND</code>  Boolean.  If FALSE, then the wind component to calculating the WSV statistic in the FBP standard is set to 0.0.  If TRUE, then the wind speed is used as provided.
            </ul>
            bit flags, defined in FireEngine_Ext.h For consistency of outputs, these flags should match those provided to determine the ROS values.
\param cfb  Calculated value, crown fraction burned (unitless).
\param cfc  Calculated value, crown fuel consumption (kg/m2).
\param rso  Calculated value, critical spread rate for crowning
\param csi  Calculated value, critical surface intensity for crowning
\param sfc  Calculated value, surface fuel consumption (kg/m2).
\param tfc  Calculated value, total fuel consumption (kg/m2).
\param fi   Calculated value, fire intensity.
\sa ICWFGM_Fuel::CalculateFCValues

\retval E_POINTER   The address of any pointers passed into the function (cfb, cfc, sfc, tfc or fi) are invalid
\retval S_OK        Successful
\retval E_INVALIDARG        Invalid inputs have caused (likely) a divide by zero error.

STDMETHOD() CCWFGM_Fuel::CalculateROSValues	(	double	GS,
		double	SAZ,
		double	WS,
		double	WAZ,
		double	BUI,
		double	FMC,
		double	FFMC,
		double	fF,
		ULONGLONG	t,
		ULONGLONG	ffmc_t,
		short	flag,
		double *	rss,
		double *	roseq,
		double *	ros,
		double *	frss,
		double *	froseq,
		double *	fros,
		double *	brss,
		double *	broseq,
		double *	bros,
		double *	wsv,
		double *	raz
	)

Given several input parameters, calculates various of rate of spread (ROS) values. The specific set of equations used to calculate ROS values is determined by the fuel type and/or any modifications which have been applied.

Automatic caching of previously calculated values is performed for efficiency.
\param GS   Percentage ground slope specified as a decimal value (0 - 1)
\param SAZ  Slope azimuth, upslope (radians, Cartesian)
\param WS   Observed wind speed (kph)
\param WAZ  Wind azimuth (radians, Cartesian)
\param BUI  Buildup index (FWI output)
\param FMC  Foliar moisture code (FBP output) (0-1)
\param FFMC Fine fuel moister code (FWI output)
\param fF   Fine fuel moisture function in the ISI (FWI output)
\param t    Time in seconds since ignition,  used for purposes of calculating acceleration
\param ffmc_t       Time in seconds for the duration used to calculate FFMC
\param flag A combination of
            <ul>
            <li><code>CWFGM_SCENARIO_OPTION_ACCEL</code>  Boolean.  If TRUE, then acceleration is applied to various output statistics in the FBP standard.  This value should only applicable to point ignitions.  If FALSE, then the fire is assumed to be always at equilibrium.
            <li><code>CWFGM_SCENARIO_OPTION_BUI</code>  Boolean.  If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard.
            <li><code>CWFGM_SCENARIO_OPTION_TOPOGRAPHY</code>  Boolean.  If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0.  If TRUE, then the wind speed is used as provided.  This setting also affects the slope component in Dr. Richards' 3D equations.
            <li><code>CWFGM_SCENARIO_OPTION_GREENUP</code>  Boolean.  Specific FBP fuel types use different equations during green-up.  This flag determines whether to use green-up equations or not.
            <li><code>CWFGM_SCENARIO_OPTION_WIND</code>  Boolean.  If FALSE, then the wind component to calculating the WSV output statistic in the FBP standard is set to 0.0.  If TRUE, then the wind speed is used as provided.
            </ul>
            bit flags, defined in FireEngine_Ext.h For consistency of outputs.
\param rss  Calculated value, RSS (metres per minute)
\param roseq        Calculated value, ROSeq (equilibrium rate of spread) (metres per minute)
\param ros  Calculated value, ROS (rate of spread) (metres per minute)
\param frss Calculated value, FRSS (flank RSS) (metres per minute)
\param froseq       Calculated value, FROSeq (flank equilibrium rate of spread) (metres per minute)
\param fros Calculated value, FROS (flank rate of spread) (metres per minute)
\param brss Calculated value, BRSS (back RSS) (metres per minute)
\param broseq       Calculated value, BROSeq (back equilibrium rate of spread) (metres per minute)
\param bros Calculated value, BROS (back rate of spread) (metres per minute)
\param wsv  Calculated value, WSV (wind speed vector) (metres per minute)
\param raz  Calculated value, RAZ (wind speed vector azimuth) (radians, Cartesian)
\sa ICWFGM_Fuel::CalculateROSValues

\retval E_POINTER   The address of any pointers passed into the function (rss, ros, fros, bros, wsv or raz) are invalid.
\retval S_OK        Successful
\retval E_INVALIDARG        Invalid inputs have caused (likely) a divide by zero error.

STDMETHOD() CCWFGM_Fuel::CalculateStatistics	(	double	ROS,
		double	FROS,
		double	BROS,
		double	CFB,
		ULONGLONG	time,
		short	flag,
		double *	area,
		double *	perimeter
	)

Calculates statistics of the theoretical ellipse defined by ROS, FROS, BROS.

To match the CFS code, these values should be equilibrium values.  To match Prometheus implementations, these should values should be instantaneous, after corrections through any ellipse equations.
\param ROS  Rate of spread (metres per minute).
\param FROS Flank rate of spread (metres per minute).
\param BROS Back rate of spread (metres per minute).
\param CFB  Crown fraction burned.
\param time Time since fire start, important if acceleration is turned on.
\param flag A combination of
            <ul>
            <li><code>CWFGM_SCENARIO_OPTION_ACCEL</code>  Boolean.  If TRUE, then acceleration is applied to various output statistics in the FBP standard.  This value should only applicable to point ignitions.  If FALSE, then the fire is assumed to be always at equilibrium.
            <li><code>CWFGM_SCENARIO_OPTION_BUI</code>  Boolean.  If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard.
            <li><code>CWFGM_SCENARIO_OPTION_TOPOGRAPHY</code>  Boolean.  If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0.  If TRUE, then the wind speed is used as provided.  This setting also affects the slope component in Dr. Richards' 3D equations.
            <li><code>CWFGM_SCENARIO_OPTION_GREENUP</code>  Boolean.  Specific FBP fuel types use different equations during green-up.  This flag determines whether to use green-up equations or not.
            <li><code>CWFGM_SCENARIO_OPTION_WIND</code>  Boolean.  If FALSE, then the wind component to calculating the WSV statistic in the FBP standard is set to 0.0.  If TRUE, then the wind speed is used as provided.
            </ul>
            bit flags, defined in FireEngine_Ext.h. For consistency of outputs, these flags should match those provided to determine the ROS values.
\param area Calculated value, fire area.
\param perimeter    Calculated value, fire perimeter..
\sa ICWFGM_Fuel::CalculateStatistics

\retval E_POINTER   the address provided is invalid
\retval S_OK        Successful
\retval E_INVALIDARG        Invalid inputs have caused an error

STDMETHOD() CCWFGM_Fuel::Clone ( ICWFGM_Fuel ** newFuel )

Creates a new fuel object with properties which are identical to that of the object being called, returns a handle to the new object in newFuel.

Parameters

newFuel Address of memory to contain the reference for a newly created fuel object.

See Also: ICWFGM_Fuel::Clone

Return values

E_POINTER	The address provided for newFuel is invalid
S_OK	Successful
E_OUTOFMEMORY	Insufficient memory
ERROR_SEVERITY_WARNING	Unspecified failure
E_NOINTERFACE	Interface does not exist

STDMETHOD() CCWFGM_Fuel::FMC	(	double	lat,
		double	lon,
		double	elev,
		USHORT	day,
		double *	fmc
	)

Calculates the FMC (foliar moisture content) value based on several parameters. If elevation is negative, then the normalized latitude is calculated based on equation 1 of "Development and the Structure of the Canadian Forest Fire Behaviour Prediction System -Information Report ST-X-3", otherwise it is calculated from equation 3. Similarly, minimum FMC is calculated using either equation 2 or 4.

If the latitude and longitude are outside the general extents of Canada (latitude: 42 to 83 degrees, longitude: -52 to -141 degrees), then the latitude and/or longitude are modified to be within these ranges.
\param lat Specific location (latitude, radians, signed) on the earth's surface.
\param lon Specific location (longitude, radians, signed) on the earth's surface.
\param elev Elevation of the specific location (metres) from sea level.
\param day Julian day (day of the year, 0-365)
\param fmc The calculated FMC value (percentage value expressed as a decimal 0-1).
\sa ICWFGM_Fuel::FMC

\retval E_POINTER The address provided for fmc is invalid
\retval S_OK Successful
\retval E_INVALIDARG An input value is out of range or has caused (likely) a divide by zero error.

STDMETHOD() CCWFGM_Fuel::get_C2 ( ICWFGM_Fuel ** pVal )

These properties are used only for M-1, M-2 fuel types. They define extra parameters that are needed for those fuel types. For any other fuel types, these parameters are unused. C-2 and D-1 are pointers to ICWFGM_Fuel objects which represent the appropriate fuel type. If the fuel type is not mixed (or modified), then attempts to get or set these parameters will result in a returned error code. Specific rules regarding this error code are expected to change slightly. Retrieval of C-2 or D-1 pointer values does not modify the COM reference counter for either of these objects. Assignment will increment the reference counter for the new object and decrement the reference counter for the old object.

Parameters

pVal	The fuel type name.

See Also: ICWFGM_FBPFuel::C2

Return values

E_POINTER	The address provided for newVal is invalid.
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::get_D1 ( ICWFGM_Fuel ** pVal )

These properties are used only for M-1, M-2 fuel types. They define extra parameters that are needed for those fuel types. For any other fuel types, these parameters are unused. C-2 and D-1 are pointers to ICWFGM_Fuel objects which represent the appropriate fuel type. If the fuel type is not mixed (or modified), then attempts to get or set these parameters will result in a returned error code. Specific rules regarding this error code are expected to change slightly. Retrieval of C-2 or D-1 pointer values does not modify the COM reference counter for either of these objects. Assignment will increment the reference counter for the new object and decrement the reference counter for the old object.

Parameters

pVal	When retrieving the property.

See Also: ICWFGM_FBPFuel::D1

Return values

E_POINTER	The address provided for pVal is invalid.
S_OK	Successful.

STDMETHOD() CCWFGM_Fuel::get_Name ( BSTR * pVal )

The name of the fuel type.

Parameters

pVal	The fuel type name.

See Also: ICWFGM_Fuel::Name; ICWFGM_FBPFuel::Name

Return values

E_POINTER	The address provided for pVal is invalid.
E_FAIL	An attempt to change the name of a read-only fuel type was a tried.
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::get_UserData ( VARIANT * pVal )

This property is unused by the fuel 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

pVal	when retrieving the property

See Also: ICWFGM_Fuel::UserData

Return values

E_POINTER	the address provided for pVal is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::GetAttribute	(	USHORT	option,
		VARIANT *	value
	)

Polymorphic. Gets a particular attribute for a fuel. Each fuel type comprises of a variety of equations and values. This function allows the client application to retrieve most any value that would define some aspect of the calculations for this fuel type.

Parameters

option	This parameter identifies which attribute value to retrieve. Refer to the following table for key values and descriptions.
value	The value of the attribute being requested.

See Also: ICWFGM_Fuel::GetAttribute

Return values

E_POINTER	The address provided for attribute is invalid.
S_OK	Successful.
E_UNEXPECTED	The fuel type (or some aspect of it) is inconsistent with the attribute requested (e.g. asking for attribute A from a mixed fuel type).

STDMETHOD() CCWFGM_Fuel::GetDefaultCLSID ( CLSID * clsID )

Returns the default CLSID for this fuel type. A CLSID is the identifier for the class of a COM object. For read-only fuel types, this value is set to the same class as itself. I.e., it's default fuel type is itself. For read/write fuel types which were cloned from another fuel type, this value is set to the class of the original default fuel type used to create it. I.e., if a C-1 fuel type was cloned into a read/write fuel type, this value would be the CLSID for the C-1 read-only fuel type. This value is unused by this COM DLL and may be removed in future releases. Its purpose is to facilitate the client application ability to reset a fuel type back to its default values.

Parameters

clsID return value for CLSID

See Also: ICWFGM_Fuel::GetDefaultCLSID

Return values

E_POINTER	The address provided for clsId is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::GetEquation	(	USHORT	equationKey,
		USHORT *	equation
	)

Given a request for a specific type of equation, retrieves the index for the specific equation (set) used for a particular calculation.

Parameters

equationKey	One of the following values, as defined in FuelCOM_ext.h FUELCOM_EQUATION_FMC FUELCOM_EQUATION_SFC FUELCOM_EQUATION_SFC_GREENUP FUELCOM_EQUATION_TFC FUELCOM_EQUATION_TFC_GREENUP FUELCOM_EQUATION_RSI FUELCOM_EQUATION_RSI_GREENUP FUELCOM_EQUATION_ISF FUELCOM_EQUATION_ISF_GREENUP FUELCOM_EQUATION_CFB FUELCOM_EQUATION_CFB_GREENUP FUELCOM_EQUATION_ACCEL FUELCOM_EQUATION_LB
equation	Index of the requested equation. Refer to the following table for equation indices and what they refer to.

See Also: ICWFGM_FBPFuel::GetEquation

Return values

E_POINTER	The address provided for equation index is invalid.
S_OK	Successful.
E_INVALIDARG	The equationKey index is invalid.

STDMETHOD() CCWFGM_Fuel::IsC6FuelType ( VARIANT_BOOL * retbool )

Reports whether the fuel type is C-6. This fuel type information is retained after cloning a read-only template into a read/write fuel type. This information will become invalid once an equation in the read/write fuel has been replaced.

Parameters

retbool result of the test

See Also: ICWFGM_Fuel::IsC6FuelType

Return values

E_POINTER	the address provided for retbool is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::IsConiferFuelType ( VARIANT_BOOL * retbool )

Reports whether the fuel type is C-1, C-2, C-3, C-4, C-5, C-6, or C-7. This fuel type information is retained after cloning a read-only template into a read/write fuel type. This information will become invalid once an equation in the read/write fuel has been replaced.

Parameters

retbool Always false / 0

See Also: ICWFGM_Fuel::IsConiferFuelType

Return values

E_POINTER	the address provided for retbool is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::IsDeciduousFuelType ( VARIANT_BOOL * retbool )

Reports whether the fuel type is D-1, D-2, or D-1/D-2. This fuel type information is retained after cloning a read-only template into a read/write fuel type. This information will become invalid once an equation in the read/write fuel has been replaced.

Parameters

retbool Always false / 0

See Also: ICWFGM_Fuel::IsDeciduousFuelType

Return values

E_POINTER	the address provided for retbool is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::ISF	(	double	RSF,
		double	SF,
		double	ISZ,
		short	flag,
		double *	isfValue
	)

Calculates the value for ISF based on parameters passed in. Note that this method is used by mixed fuel types only and likely should not be called directly. Automatic caching of previously calculated values is performed for efficiency.

Parameters

RSF	Intermediate output for calculating ROS values.
SF	Slope factor.
ISZ	Dead wind ISI.
flag	A combination of `CWFGM_SCENARIO_OPTION_ACCEL` Boolean. If TRUE, then acceleration is applied to various output statistics in the FBP standard. This value should only applicable to point ignitions. If FALSE, then the fire is assumed to be always at equilibrium. `CWFGM_SCENARIO_OPTION_BUI` Boolean. If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard. `CWFGM_SCENARIO_OPTION_TOPOGRAPHY` Boolean. If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. This setting also affects the slope component in Dr. Richards' 3D equations. `CWFGM_SCENARIO_OPTION_GREENUP` Boolean. Specific FBP fuel types use different equations during green-up. This flag determines whether to use green-up equations or not. `CWFGM_SCENARIO_OPTION_WIND` Boolean. If FALSE, then the wind component to calculating the WSV statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. bit flags, defined in FireEngine_Ext.h. For consistency of outputs, these flags should match those provided to determine the ROS values.
isfValue	the calculated ISF value

See Also: CCWFGM_Fuel::ISF

Return values

E_POINTER	The address provided for the calculated value is invalid
S_OK	Successful
E_INVALIDARG	Invalid inputs have caused (likely) a divide by zero error.

STDMETHOD() CCWFGM_Fuel::IsGrassFuelType ( VARIANT_BOOL * retbool )

Reports whether the fuel type is O-1a or O-1b. This fuel type information is retained after cloning a read-only template into a read/write fuel type. This information will become invalid once an equation in the read/write fuel has been replaced.

Parameters

retbool result of the test

See Also: ICWFGM_Fuel::IsGrassFuelType

Return values

E_POINTER	the address provided for retbool is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::IsMixedDeadFirFuelType ( VARIANT_BOOL * retbool )

Reports whether the fuel type is M-3 or M-4. This fuel type information is retained after cloning a read-only template into a read/write fuel type. This information will become invalid once an equation in the read/write fuel has been replaced.

Parameters

retbool result of the test

See Also: ICWFGM_Fuel::IsMixedDeadFirFuelType

Return values

E_POINTER	the address provided for retbool is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::IsMixedFuelType ( VARIANT_BOOL * retbool )

Reports whether the fuel type is M-1 or M-2. This fuel type information is retained after cloning a read-only template into a read/write fuel type. This information will become invalid once an equation in the read/write fuel has been replaced.

Parameters

retbool result of the test

See Also: ICWFGM_Fuel::IsMixedFuelType

Return values

E_POINTER	the address provided for retbool is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::IsNonFuel ( VARIANT_BOOL * retbool )

Reports whether the fuel type is non-fuel. This fuel type information is retained after cloning a read-only template into a read/write fuel type. This information will become invalid once an equation in the read/write fuel has been replaced.

Parameters

retbool result of the test

See Also: ICWFGM_Fuel::IsNonFuel

Return values

E_POINTER	the address provided for retbool is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::IsSlashFuelType ( VARIANT_BOOL * retbool )

Reports whether the fuel type is S-1, S-2, or S-3. This fuel type information is retained after cloning a read-only template into a read/write fuel type. This information will become invalid once an equation in the read/write fuel has been replaced.

Parameters

retbool result of the test

See Also: ICWFGM_Fuel::IsSlashFuelType

Return values

E_POINTER	the address provided for retbool is invalid
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::MT_Lock	(	USHORT	exclusive,
		USHORT	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 only needed for calls to this object via this interface. Method calls from the other interface are already multithreading friendly.

Parameters

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.

See Also: ICWFGM_Fuel::MT_Lock

Return values

SUCCESS_STATE_OBJECT_UNLOCKED	Lock was released.
SUCCESS_STATE_OBJECT_LOCKED_WRITE	Exclusive/write lock obtained
SUCCESS_STATE_OBJECT_LOCKED_SCENARIO	A scenario has successfully locked the fuel type for simulation(shared read lock obtained)
SUCCSS_STATE_OBJECT_LOCKED_READ	Shared/read lock obtained
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::put_C2 ( ICWFGM_Fuel * newVal )

These properties are used only for M-1, M-2 fuel types. They define extra parameters that are needed for those fuel types. For any other fuel types, these parameters are unused. C-2 and D-1 are pointers to ICWFGM_Fuel objects which represent the appropriate fuel type. If the fuel type is not mixed (or modified), then attempts to get or set these parameters will result in a returned error code. Specific rules regarding this error code are expected to change slightly. Retrieval of C-2 or D-1 pointer values does not modify the COM reference counter for either of these objects. Assignment will increment the reference counter for the new object and decrement the reference counter for the old object.

Parameters

newVal When setting the property.

See Also: ICWFGM_FBPFuel::C2

Return values

E_POINTER	The address provided for pVal is invalid.
S_OK	Successful.
E_UNEXPECTED	The fuel type which is being asked to assign a C-2 or D-1 value is not mixed.
E_NOINTERFACE	The object that the pointer being passed as C-2 (or D-1) represents does not support the ICWFGM_Fuel interface.
ERROR_SCENARIO_SIMULATION_RUNNING	The current scenario uses this fuel type and is running, the fuel cannot be changed at this time.

STDMETHOD() CCWFGM_Fuel::put_D1 ( ICWFGM_Fuel * newVal )

These properties are used only for M-1, M-2 fuel types. They define extra parameters that are needed for those fuel types. For any other fuel types, these parameters are unused. C-2 and D-1 are pointers to ICWFGM_Fuel objects which represent the appropriate fuel type. If the fuel type is not mixed (or modified), then attempts to get or set these parameters will result in a returned error code. Specific rules regarding this error code are expected to change slightly. Retrieval of C-2 or D-1 pointer values does not modify the COM reference counter for either of these objects. Assignment will increment the reference counter for the new object and decrement the reference counter for the old object.

Parameters

newVal When setting the property.

See Also: ICWFGM_FBPFuel::D1

Return values

E_POINTER	The address provided for pVal is invalid.
S_OK	Successful.
E_UNEXPECTED	The fuel type which is being asked to assign a C-2 or D-1 value is not mixed.
E_NOINTERFACE	The object that the pointer being passed as C-2 (or D-1) represents does not support the ICWFGM_Fuel interface.
ERROR_SCENARIO_SIMULATION_RUNNING	The current scenario uses this fuel type and is running, the fuel cannot be changed at this time.

STDMETHOD() CCWFGM_Fuel::put_Name ( const BSTR newVal )

Get the name of the fuel type.

Parameters

newVal The fuel type name.

See Also: ICWFGM_Fuel::Name; ICWFGM_FBPFuel::Name

Return values

E_POINTER	The address provided for pVal is invalid.
S_OK	Successful

STDMETHOD() CCWFGM_Fuel::put_UserData ( VARIANT newVal )

This property is unused by the fuel 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

newVal when setting the property

See Also: ICWFGM_Fuel::UserData

Return values

S_OK	Successful

STDMETHOD() CCWFGM_Fuel::RSI	(	double	FFMC,
		double	BUI,
		double	FMC,
		double	ISI,
		short	flag,
		double *	rsi
	)

Calculates RSI (initial rate of spread) without BUI effect. Note that this routine may seem redundant to CalculateROSValues() but is used by mixed fuel types. Typically CalculateROSValues) should be called. Automatic caching of previously calculated values is performed for efficiency.

Parameters

FFMC	Fine fuel moister code (FWI output)
BUI	Buildup index (FWI output)
FMC	Foliar moisture code (FBP output) (0-1)
ISI	Initial spread index (FWI output). Note that the FBP version of the ISI calculation (in the FWI module) should be used.
flag	A combination of `CWFGM_SCENARIO_OPTION_ACCEL` Boolean. If TRUE, then acceleration is applied to various output statistics in the FBP standard. This value should only applicable to point ignitions. If FALSE, then the fire is assumed to be always at equilibrium. `CWFGM_SCENARIO_OPTION_BUI` Boolean. If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard. `CWFGM_SCENARIO_OPTION_TOPOGRAPHY` Boolean. If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. This setting also affects the slope component in Dr. Richards' 3D equations. `CWFGM_SCENARIO_OPTION_GREENUP` Boolean. Specific FBP fuel types use different equations during green-up. This flag determines whether to use green-up equations or not. `CWFGM_SCENARIO_OPTION_WIND` Boolean. If FALSE, then the wind component to calculating the WSV statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. bit flags, defined in FireEngine_Ext.h. For consistency of outputs, these flags should match those provided to determine the ROS values.
rsi	The calculated RSI value

See Also: ICWFGM_Fuel::RSI

Return values

E_POINTER	The address provided for rsi is invalid
S_OK	Successful
E_INVALIDARG	Invalid inputs have caused (likely) a divide by zero error.

STDMETHOD() CCWFGM_Fuel::SetAttribute	(	USHORT	option,
		VARIANT	value
	)

Polymorphic. Sets a particular attribute for a fuel. This method can be used to modify some generic value associated with the fuel, or most any coefficient of specific equations used to calculated values for the fuel.

Parameters

option	This parameter identifies which attribute value to set. Refer to following table for key values and descriptions.
value	The value of the attribute to be set.

See Also: ICWFGM_Fuel::SetAttribute

Return values

S_OK	Successful.
E_UNEXPECTED	The fuel type (or some aspect of it) is inconsistent with the attribute requested (e.g. trying to set attribute A for a mixed fuel type).
ERROR_SCENARIO_SIMULATION_RUNNING	Value cannot be changed as it is being used in a currently running simulation.

STDMETHOD() CCWFGM_Fuel::SetDefaultCLSID ( CLSID * clsID )

Sets the default CLSID. Typically this value identifies the original read-only fuel type used to create/clone the fuel type, but can be used to store any value (because this value is unused by this COM DLL).

Parameters

clsID the default CLSID

See Also: ICWFGM_FBPFuel::SetDefaultCLSID

Return values

E_POINTER	The address provided for clsId is invalid
S_OK	Successful
ERROR_SCENARIO_SIMULATION_RUNNING	Value cannot be changed as it is being used in a currently running simulation

STDMETHOD() CCWFGM_Fuel::SetEquation	(	USHORT	equationKey,
		USHORT	equation
	)

Requests to change a specific equation defining part of the operations for the fuel type. If the request matches the type of the current equation, then nothing is performed. Once a given equation format has been chosen, virtually any coefficient or attribute of that equation (set) can be modified using the method SetAttribute.

Parameters

equationKey	One of the following values, as defined in FuelCOM_ext.h FUELCOM_EQUATION_FMC FUELCOM_EQUATION_SFC FUELCOM_EQUATION_SFC_GREENUP FUELCOM_EQUATION_TFC FUELCOM_EQUATION_TFC_GREENUP FUELCOM_EQUATION_RSI FUELCOM_EQUATION_RSI_GREENUP FUELCOM_EQUATION_ISF FUELCOM_EQUATION_ISF_GREENUP FUELCOM_EQUATION_CFB FUELCOM_EQUATION_CFB_GREENUP FUELCOM_EQUATION_ACCEL FUELCOM_EQUATION_LB
equation	The index identifying the equation to be set. Refer to the following table for equestion indices and what they refer to.

See Also: ICWFGM_FBPFuel::SetEquation

Return values

E_INVALIDARG	The type of equation was invalid or did not match the equationKey type
FUELCOM_SUCCESS_NO_CHANGE	If the setting of the equation resulted in no actual change to the equation
ERROR_SCENARIO_SIMULATION_RUNNING	Value cannot be changed as it is being used in a currently running scenario
S_OK	Success

STDMETHOD() CCWFGM_Fuel::SFC	(	double	FFMC,
		double	BUI,
		short	flag,
		double *	sfc
	)

Calculates the SFC (surface fuel consumption) value based on several parameters. Note that this routine may seem redundant to CalculateFCValues() but is used by mixed fuel types. Typically, the CalculateFCValues() method should be called. Automatic caching of previously calculated values is performed for efficiency.

Parameters

FFMC	Fine fuel moister code (FWI output)
BUI	Buildup index (FWI output)
flag	A combination of `CWFGM_SCENARIO_OPTION_ACCEL` Boolean. If TRUE, then acceleration is applied to various output statistics in the FBP standard. This value should only applicable to point ignitions. If FALSE, then the fire is assumed to be always at equilibrium. `CWFGM_SCENARIO_OPTION_BUI` Boolean. If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard. `CWFGM_SCENARIO_OPTION_TOPOGRAPHY` Boolean. If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. This setting also affects the slope component in Dr. Richards' 3D equations. `CWFGM_SCENARIO_OPTION_GREENUP` Boolean. Specific FBP fuel types use different equations during green-up. This flag determines whether to use green-up equations or not. `CWFGM_SCENARIO_OPTION_WIND` Boolean. If FALSE, then the wind component to calculating the WSV statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. bit flags, defined in FireEngine_Ext.h. For consistency of outputs, these flags should match those provided to determine the ROS values.
sfc	the calculated SFC value

See Also: ICWFGM_Fuel::SFC

Return values

E_POINTER	the address provided for sfc is invalid
S_OK	Successful
E_INVALIDARG	Invalid inputs have caused (likely) a divide by zero error.

COM Programmer Documentation

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation