HeroEngine Extension Interface
- Note: This page gives a general overview of HeroEngine Extension Interfaces. For implementation details, please see the HEHeightmapImportSample download.
In order to support extensibility to new data formats and features, HeroBlade supports HeroEngine Extension Interfaces (HSEI) defined as C style functions exported from dynamically loadable modules; .DLL's on Windows, .so's on Linux platforms.
This page describes each of the extension interfaces.
The HeroBlade extension interface is documented in HeroBladeExtensionInterface.h in the download package.
Each interface relevant to HeroBlade has a section in this file.
All interfaces are defined as C style functions in order to provide flexibility in the implementation of the extension module.
Extension modules are .DLL's on Windows, .so's on Linux platforms
Heightmap Import (HMI) Extension
The Heightmap Import (HMI) extension allows the HeroBlade heightmap import system to be extended through the creation of new, optional modules.
Each module exposes, or exports, several required or optional functions through a C style function declaration as defined in HeroBladeExtensionInterface.h
HMI functions are prefaces with the HMI_ moniker.
Heightmap Import (HMI) Functions
Each function and return codes are documented more specifically in HeroBladeExtensionInterface.h
In brief, the following functions are exposed by HMI implementers.
Called once when the module is loaded.
extern "C" OPTIONAL HEEXT_API int HMI_Initialize(void);
Called once when the module is being unloaded.
extern "C" OPTIONAL HEEXT_API int HMI_Shutdown(void);
Returns a delimited list of supported file types.
extern "C" REQUIRED HEEXT_API WCHAR *HMI_GetSupportedFileTypes(void);
Returns whether a specific file type is supported by the extension.
extern "C" REQUIRED HEEXT_API int HMI_IsFileTypeSupported(const WCHAR *pFileType);
Imports the data from the file, or prepares the data for further access.
extern "C" REQUIRED HEEXT_API int HMI_ImportDataFromFile(IN const WCHAR *fname);
Returns more detailed information in the event of an error.
extern "C" REQUIRED HEEXT_API WCHAR *HMI_GetErrorMessage(void);
Returns the number of columns, or width (x), of the data
extern "C" REQUIRED HEEXT_API unsigned int HMI_GetColumnCount(void);
Returns the number of rows, or depth (z), or incorrectly height (y), of the data
extern "C" REQUIRED HEEXT_API unsigned int HMI_GetRowCount(void);
Returns the data itself in 32 bit signed float format
extern "C" REQUIRED HEEXT_API float *HMI_GetData(void);
Returns a specific data point in 32 bit signed float format
extern "C" REQUIRED HEEXT_API float HMI_GetDataPoint(IN unsigned int dwColumn, IN unsigned int dwRow);
Returns the range of the data
extern "C" REQUIRED HEEXT_API float HMI_GetHeightRange(IN OUT float *pfMin, IN OUT float *pfMax);
Called once the import begun with HMI_ImportDataFromFile has completed and data is no longer needed.
extern "C" REQUIRED HEEXT_API void HMI_ImportCompleted(void);
Specifying Available Heightmap Import Extensions
Available Heightmap import extensions are listed in the heightmapimport section of the HeroEngineExtensions.dev file. This is an optional file which is created in the HeroEngine executable directory (same directory as heroblade.exe).
Sample format of HeroEngineExtensions.dev
[heightmapimport] Importer=HeightmapImportRaw.dll PNGSupport=c:\dev\HeightmapImportPNG\debug\HeightmapImportPNG.dll
Each line contains one available heightmap import extension, in the format key = value.
The contents of the key are only relevant for human-readable organization, as they are not displayed or utilized by HeroBlade.
The value specifies the module which implements the heightmap import extension interface.
Modules without path qualifiers are assumed to be in the HeroEngine executable directory (same directory as heroblade.exe).
The HEHeightmapImportSample contains a sample implementation of a heightmap import extension for raw format files. It supports 8 bit, 16 bit, and 32 bit raw files.