API

#ifndef _MILSYMBOL_H_INCLUDED
#define _MILSYMBOL_H_INCLUDED
// This is the C API for MilSymbol functionality
#ifdef __cplusplus
extern "C" {
#endif

// BUILDING_TOOLS must be defined when building the DLL for Windows
#if defined(MILSYMBOL_APISTATIC)
    #define MILSYMBOL_APIPUBLIC
    #define MILSYMBOL_APIPRIVATE
#else
#if defined(_WIN32)
	#ifdef BUILDING_MILSYM // <-- This is unique per DLL
		#define MILSYMBOL_APIPUBLIC __declspec(dllexport)
		#define MILSYMBOL_APIPRIVATE
	#else
		#define MILSYMBOL_APIPUBLIC __declspec(dllimport)
		#define MILSYMBOL_APIPRIVATE
	#endif
#elif defined(__GNUC__)
	#define MILSYMBOL_APIPUBLIC __attribute__ ((visibility("default")))
	#define MILSYMBOL_APIPRIVATE __attribute__ ((visibility("hidden")))
#else
	#define MILSYMBOL_APIPUBLIC
	#define MILSYMBOL_APIPRIVATE
#endif
#endif

typedef void *MilSymbolContextRef;
typedef const void *MilSymbolRef;
typedef const char *MilSymbolSVGRef; // SVG is XML text
typedef const char *MilSymbolInstructionsRef; // Instructions is prioprietary text
typedef const void *MilSymbolCanvasRef; // canvas is a bitmap

// client sets up the dimension and options (affiliation, SIDC type, etc.)
// The symbol generator is setup (constructed)
// One or more SIDC is sent to the symbol generator.  It creates a map of SIDC to InstructionSet for later recall
// For each SIDC, construct metadata and generate instruction set
// For any instruction set, can produce SVG or canvas or other.
// Client must destroy instruction set when done with it.

// caching an instruction set per SIDC would be per symbol generator?
// Once a SIDC has produced an instruction set, the generator is no longer needed.
// Caching can be done outside of the symbol generation.

// startup the MilSymbol API
extern MILSYMBOL_APIPUBLIC void MilSymbolStartup();

// shutdown the MilSymbol API
extern MILSYMBOL_APIPUBLIC void MilSymbolShutdown();

// Set default style options to be used by subsequent symbol contexts created
// Style options are described in text via key:value pairs enclosed in braces.
// Available style options:
//   "alternateMedal" (boolean) 2525D lets you choose between MEDAL (false) icn and alternate MEDAL (true) icn for Mines; default is set to MEDAL (false).
//   "civilianColor" (boolean) Use the Civilian Purple defined in 2525 (true) or not (false). defaults to true.
//   "colorMode" (string) 2525C Allows "Dark", "Medium", or "Light" colors. defaults to Light
//   "engagementType" (string) Engagement Bar Type, should be one of "TARGET", "NON-TARGET", or "EXPIRED"
//   "fill" (boolean) The icon will be filled with color (true) or not (false).  defaults to true
//   "fillOpacity" (float) fill opacity range is 0.0 to 1.0. defaults to 1.0 (fully opaque)
//   "fontfamily" (string) The font family to use.  defaults to "Arial"
//   "frame" (boolean) Frame the icon (true) or not (false).  defaults to true.
//   "frameColor" (color) Use this color for the frame.  defaults to no color (transparent)
//   "hqStaffLength" (integer) The default length of the HQ staff (defaults to 0) 100 pixels?
//   "icon" (boolean) display the icon (true) or not (false).  defaults to true.
//   "iconColor" (color) Use this color for the icon.  defaults to no color (transparent) (per-affiliation supported)
//   "infoBackground" (color) Color of square behind texts.  defaults to no color. (per-affiliation)
//   "infoBackgroundFrame" (color) Color of the squares frame.  defaults to no color.
//   "infoColor" (color) Color of the info fields.  defaults to no color (false). (per-affiliation supported)
//   "infoFields" (boolean) Allow display of all info fields (true) or not (false).  defaults to true.
//   "infoOutlineColor" (color); // Color of the text outline.  defaults to "rgb(239, 239, 239)"
//   "infoOutlineWidth" (float) (Width of the text-field outline.  defaults to 0
//   "infoSize" (float) Relative size of the info fields.  defaults to 40
//   "monoColor" (Color) The icon is this monocromatic color. defaults to false (is not monochromatic)
//   "outlineColor" (color) Color of the outline.  defaults to "rgb(239, 239, 239)" (per-affiliation supported)
//   "outlineWidth" (float) Width of the outline.  defaults to 0.0
//   "padding" (float) Extra padding around the symbol.  defaults to 0.0
//   "simpleStatusModifier" (boolean) Force use of simple status modifiers (true) or not (false).  defaults to false.
//   "size" (float) The symbol size is actually the L variable in the symbols so the symbol will be larger than this size.  defaults to 100
//   "square" (boolean) The symbol should be square (true) or not (false).  defaults to false.
//   "standard" (string) Standards to use: "APP6" or "2525".  defaults to "2525" 
//   "strokeWidth" (float) The stroke width of the icon frame. defaults to 4
// Style Value Types:
//   boolean: "false", "true", "0", "1"
//   color: "rgb(red, green, blue)" (opaque), rgba(red, green, blue, alpha)" (semi-transparent), ("false" for no-color/transparent)
//   string: text (ASCII characters only)
//   integer: whole integer number (-,+,0,1,2,3,4,5,6,7,8,9 characters)
//   float: floating point number (-,+,.,0,1,2,3,4,5,6,7,8,9 characters)
// Style string example: "{colorMode:Dark} {fontFamily:Courier}{icon:false} {monoColor:rgb(200,20,20)}"
// 
// Utility Styles:
//   "dump-icons" (string) output known icons as SVG files to a supplied directory (path) 
//
// per-affiliation colors are encoded with affiliation=color.  With no affiliation specified, the color is normally applied.
// An affiliation-specific color overrides the non-affiliated color.
// Affiliations include: "friend", "neutral", "hostile", "unknown"
//   example: "{outlineColor:friend=rgb(220,20,20);rgb(100,100,100);hostile=RGB(0,0,100)}" 
//   In the above example, the outlineColor is completely replaced with the given colors; meaning that "neutral" affiliation is replaced as well.
extern MILSYMBOL_APIPUBLIC void MilSymbolSetStyle(const char *style);

// Get the current set of style options as a string of key:value pairs enclosed in braces
// (see example for MilSymbolSetStyle())
// The returned string must be destroyed via MilSymbolDestroyStyleString()
extern MILSYMBOL_APIPUBLIC const char *MilSymbolGetStyle();

// reset the global style to defaults
extern MILSYMBOL_APIPUBLIC void MilSymbolResetStyle();

// destroy a style options string that was acquired via MilSymbolGetStyle() or MulSymbolContextGetStyle() 
extern MILSYMBOL_APIPUBLIC void MilSymbolDestroyStyleString(const char *style);

// Create a symbol context to generate symbols with default settings
extern MILSYMBOL_APIPUBLIC MilSymbolContextRef MilSymbolContextCreate();

// Release an existing symbol context
extern MILSYMBOL_APIPUBLIC void MilSymbolContextRelease(MilSymbolContextRef sc);

// Set style options for a symbol context.  see description for MilSymbolSetStyle()
extern MILSYMBOL_APIPUBLIC void MilSymbolContextSetStyle(MilSymbolContextRef sc, const char *style);

// reset the context style to the current global style
extern MILSYMBOL_APIPUBLIC void MilSymbolContextResetStyle(MilSymbolContextRef sc);

// Get the style options for a symbol context as a string of key:value pairs enclosed in braces
// (see example for MilSymbolSetStyle())
// The returned string must be destroyed via MilSymbolDestroyStyleString()
extern MILSYMBOL_APIPUBLIC const char *MilSymbolContextGetStyle(MilSymbolContextRef sc);

// A symbol is made up of various information (provided in fields).
// Many of these fields can be defined directly via the description provided to MilSymbolContextGenerateSymbol().
// Some are embedded in the SIDC:
//Field A: Symbol Icon
//    The innermost part of a symbol that represents a joint military object.
//Field B: Echelon
//    A graphic amplifier in a unit symbol that identifies command level
//Field C: Quantity
//    A text amplifier in an equipment symbol that identifies the number of items present.
//Field D: Task Force Indicator
//    A graphic amplifier that identifies a unit or activities symbol as a task force.
//Field E: Frame Shape Modifier
//    A graphic modifier that displays affiliation, battle dimension, or exercise amplifying descriptors of an object.
//Field F: Reinforced or Reduced
//    A text amplifier in a unit symbol that displays (+) for reinforced, (-) for reduced, (+/-) reinforced and reduced.
//Field G: Staff Comments
//    A text amplifier for units, equipment and installations; content is implementation specific.
//Field H: Additional Information
//    A text amplifier for units, equipment and installations; content is implementation specific.
//(Field I does not exist)
//Field J: Evaluation Rating
//    A text amplifier for units, equipment and installations that consists of a one-letter reliability rating and a one-number credibility rating:
//    Reliability Ratings:
//        A-completely reliable
//        B-usually reliable
//        C-fairly reliable
//        D-not usually reliable
//        E-unreliable
//        F-reliability cannot be judged
//    Credibility Ratings:
//        1-confirmed by other sources
//        2-probably true
//        3-possibly true
//        4-doubtfully true
//        5-improbable
//        6-truth cannot be judged.
//Field K: Combat Effectiveness
//    A text amplifier for units and installations that indicates unit effectiveness or installation capability.
//Field L: Signature Equipment
//    A text amplifier for hostile equipment; “!” indicates detectable electronic signatures.
//Field M: Higher Formation
//    A text amplifier for units that indicates number or title of higher echelon command (corps are designated by Roman numerals).
//Field N: Hostile (Enemy)
//    A text amplifier for equipment; letters "ENY" denote hostile symbols.
//(Field O does not exist)
//Field P: IFF/SIF/AIS
//    A text amplifier displaying IFF/SIF/AIS Identification modes and codes.
//Field Q: Direction of Movement Indicator
//    A graphic amplifier for units and equipment that identifies the direction of movement or intended movement of an object.
//Field R: Mobility Indicator
//    A graphic amplifier for equipment that depicts the mobility of an object.
//Field R2: SIGINT Mobility Indicator
//    M = Mobile, S = Static, or U = Uncertain.
//Field S: Headquarters Staff Indicator/Offset Location Indicator 
//    Headquarters staff indicator:
//        A graphic amplifier for units, equipment and installations that identifies a unit as a headquarters.
//    Offset location indicator:
//        A graphic amplifier for units, equipment and installations used when placing an object away from its actual location.
//Field T: Unique Designation
//    A text amplifier for units, equipment and installations that uniquely identifies a particular symbol or track number.
//    Identifies acquisitions number when used with SIGINT symbology.
//Field V: Type
//    A text amplifier for equipment that indicates types of equipment.
//Field W: Date/Time Group (DTG)
//    An alphanumeric designator for displaying a date-time group (DDHHMMSSZMONYYYY) or “O/O” for on order.
//    The date-time group is composed of a group of six numeric digits with a time zone suffix and
//    the standardized three-letter abbreviation for the month followed by four digits representing the year.
//    The first pair of digits represents the day; the second pair, the hour; the third pair, the minutes.
//    For automated systems, two digits may be added before the time zone suffix and after the minutes to designate seconds.
//Field X: Altitude/Depth
//    A text modifier for units, equipment, and installations,that displays altitude, depth; or height of equiupment or structures on the ground
//Field Y: Location
//    A text amplifier for units, equipment and installations that displays a symbol’s location in degrees, minutes and decimal minutes (or in MGRS or other applicable display format).
//Field Z: Speed
//    A text amplifier for units and equipment that displays velocity as set forth in MIL-STD-6040.
//Field AA: Special C2 Headquarters
//    A text modifier for units; indicator is contained inside the frame; contains the name of the special C2 Headquarters.
//Field AB: Feint/Dummy Indicator
//    A graphic amplifier for units, equipment and installations that identifies an offensive or defensive unit intended to draw the enemy’s attention away from the area of the main attack.
//Field AC: Installation
//    A graphic amplifier for units, equipment and installations used to show that a particular symbol denotes an installation.
//Field AD: Platform Type
//    Electronic intelligence notation (ELNOT) or communications intelligence notation (CENOT)
//Field AE: Equipment Teardown Time
//    Equipment teardown time in minutes.
//Field AF: Common Identifier
//    Example: “Hawk” for Hawk SAM system.
//Field AG: Auxiliary Equipment Indicator
//    Towed sonar array indicator: A graphic modifier for equipment that indicates the presence of a towed sonar array. 
//Field AH: Area of Uncertainty
//    A graphic modifier for units, equipment and installations that indicates the area where an object is most likely to be, based on the object’s last report and the reporting accuracy of the sensor that detected the object.
//Field AI: Dead Reckoning Trailer
//    A graphic amplifier for units and equipment that identifies where an object should be located at present, given its last reported course and speed.
//Field AJ: Speed Leader
//    A graphic amplifier for units, equipment and installations that depicts the speed and direction of movement of an object.
//Field AK: Pairing Line
//    A graphic amplifier for units, equipment and installations that connects two objects and is updated dynamically as the positions of the objects change.
//Field AL: Operational Condition
//    A graphic amplifier for equipment or installations that indicates operational condition or capacity.
//Field AO: Engagement Bar
//    A graphic amplifier placed immediately atop the symbol.
//    May denote, 1) local/remote status; 2) engagement status; and 3) weapon type.
//Field AP: Target Designator
//    A six character text modifier used in Fire Support operations to
//    uniquely designate targets in accordance with STANAG 2147,
//    where characters 1 and 2 are alphabetic, and characters 3-6 are numeric: AANNNN.
//Field AQ: Guarded Unit
//    During ballistic missile defense, some tracks are designated as guarded by a particular unit
//Field AR: Special Designator
//    Special track designators such as Non-Real Time (NRT) and Tactically Significant (SIG) tracks are denoted here.
//Field AS: Country
//    Identifies the country of the organization being shown. Use GENC Standard

// Generate a symbol for the given SIDC interrupted from the given symbol context
// The caller is responsible for destroying the symbol via 'MilSymbolDestroySymbol()'
// A symbol survives destruction of the context used to generate it.
// A symbol can be converted to other useful forms: instruction text, SVG, raster/canvas
// The symbol is described with key:value pairs enclosed in braces.
//    "sidc" (required)
//        Symbol Identification Code: For MIL-STD-2525D - 20-digits
//            First set of ten digits:
//                Digits 1 and 2 is the Version.
//                Digits 3 and 4 is the Standard Identity.
//                Digits 5 and 6 is the Symbol Set.
//                Digit 7 is the Status.
//                Digit 8 is the Headquarters/Task Force/Dummy.
//                Digits 9 and 10 is the Amplifier/Descriptor.
//            Second set of ten digits:
//                Digits 11 and 12 is the entity.
//                Digits 13 and 14 is the entity type.
//                Digits 15 and 16 is the entity subtype.
//                Digits 17 and 18 is the first modifier.
//                Digits 19 and 20 is the second modifier.
//    "quantity" (Field C; 9 chars max)
//    "reinforcedReduced" (Field F; 3 chars max)
//    "staffComments" (Field G; 20 chars max)
//    "additionalInformation" (Field H; 20 chars max)
//    "evaluationRating" (Field J; 2 chars max)
//    "combatEffectiveness" (Field K; 5 chars max)
//    "signatureEquipment" (Field L; 1 char max)
//    "higherFormation" (Field M; 21 chars max)
//    "hostile" (Field N; 3 chars max)
//    "iffSif" (Field P; 15 chars max)
//    "direction" (Field Q; 4 chars max; degrees clockwise from up)
//    "sigint" (Field R2; 1 char max)
//    "uniqueDesignation" (Field T; 30 chars max)
//    "type" (Field V; 24 chars max)
//    "dtg" (Field W; 16 chars max.)
//    "altitudeDepth" (Field X; 14 chars max)
//    "location" (Field Y; 19 chars max)
//    "speed" (Field Z; 8 chars max)
//    "specialHeadquarters" (Field AA; 9 chars max)
//    "country" (Field AC; 3 chars)
//    "platformType" (Field AD; 6 chars max)
//    "equipmentTeardownTime" (Field AE; 3 chars max)
//    "commonIdentifier" (Field AF; 12 chars max)
//    "engagementBar" (Field AO; 8 chars max)
//    "targetNumber" (Field AP; 6 chars max)
//    "guardedUnit" (Field AQ; 3 chars max)
//    "specialDesignator" (Field AR; 3 chars max)
//The following are not related to a MIL-STD field:
//    "headquartersElement"
//    "installationComposition"
//    "speedLeader" This is the length of the speed leader in pixels, this will be independet of the size of the symbol.
extern MILSYMBOL_APIPUBLIC MilSymbolRef MilSymbolContextGenerateSymbol(MilSymbolContextRef sc, const char *description);

// Destroy a generated symbol
extern MILSYMBOL_APIPUBLIC void MilSymbolDestroySymbol(MilSymbolRef symbol);

// Obtain the bounding box for a symbol.
// An asymetrical box will have x1 != -x2 or y1 != -y2
// x1 <= x2; y1 <= y2; Coordinates increase right and upward.
extern MILSYMBOL_APIPUBLIC void MilSymbolSymbolGetBoundingBox(MilSymbolRef symbol, float *x1, float *x2, float *y1, float *y2);

// Obtain the symbol octagon anchor.
// The octagon anchor is the center of the symbol octagon guide shape relative to corner of the bounding box.
extern MILSYMBOL_APIPUBLIC void MilSymbolSymbolGetOctagonAnchor(MilSymbolRef symbol, float *x, float *y);

// This is usually the same as the octagon anchor, but will differ when headquarters is used.
extern MILSYMBOL_APIPUBLIC void MilSymbolSymbolGetAnchor(MilSymbolRef symbol, float *x, float *y);

// Store the symbol as instruction text.  A 0-termianted C-string is returned.
// The client is responsible for destroying the string
extern MILSYMBOL_APIPUBLIC MilSymbolInstructionsRef MilSymbolSymbolAsInstructions(MilSymbolRef symbol);
extern MILSYMBOL_APIPUBLIC void MilSymbolInstructionsDestroy(MilSymbolInstructionsRef instructions);

// Create a symbol from a set of instructions that were previously generated.
// The symbol can then produce svg and canvas data.
extern MILSYMBOL_APIPUBLIC MilSymbolRef MilSymbolGenerateSymbolFromInstructions(MilSymbolInstructionsRef instructions);

// Store the symbol as SVG XML.  A 0-termianted C-string is returned.
extern MILSYMBOL_APIPUBLIC MilSymbolSVGRef MilSymbolSymbolAsSVG(MilSymbolRef symbol);
extern MILSYMBOL_APIPUBLIC void MilSymbolSVGDestroy(MilSymbolSVGRef svg);

// Store the symbol into a bitmap canvas.
// The bitmap can utilize more or less detail via the 'scale' factor provided. 
// scale of 1.0 produces the normal bitmap size.  2.0 would produce twice as much detail.
#define MILSYMBOL_CANVASFORMAT_ARGB32 0 // The bitmap data is stored with 8bits per component in (alpha, red, green, blue) order (32bits per pixel).
#define MILSYMBOL_CANVASFORMAT_RGBA32 1 // The bitmap data is stored with 8bits per component in (red, green, blue, alpha) order (32bits per pixel).
#define MILSYMBOL_CANVASFORMAT_RGB24  2 // The bitmap data is stored with 8bits per component in (red, green, blue) order (24bits per pixel).
extern MILSYMBOL_APIPUBLIC MilSymbolCanvasRef MilSymbolSymbolAsCanvas(MilSymbolRef symbol, int format, float scale);

// Get the pixel width of the canvas
// The stride is the width * 4 (32bits per pixel).
extern MILSYMBOL_APIPUBLIC unsigned int MilSymbolCanvasGetWidth(MilSymbolCanvasRef canvas);

// Get the pixel height of the canvas
extern MILSYMBOL_APIPUBLIC unsigned int MilSymbolCanvasGetHeight(MilSymbolCanvasRef canvas);

// Get the ARGB bytes of the canvas as a contiguous memory chunk.  Do not modify the bytes.  The numBytes is filled in, if supplied
extern MILSYMBOL_APIPUBLIC const char *MilSymbolCanvasGetBytes(MilSymbolCanvasRef canvas, unsigned int *numBytes);

// Save the canvas to a specified file.  The file extension determines the file format, if supported.
// returns 1 for success, else 0.
extern MILSYMBOL_APIPUBLIC int MilSymbolCanvasWriteFile(MilSymbolCanvasRef canvas, const char *filename);

// destroy the canvas
extern MILSYMBOL_APIPUBLIC void MilSymbolCanvasDestroy(MilSymbolCanvasRef canvas);

#ifdef __cplusplus
}
#endif

#endif