1.. _rfc-18: 2 3================================================================================ 4RFC 18: OGR Style Support in C API 5================================================================================ 6 7Author: Daniel Morissette 8 9Contact: dmorissette@mapgears.com 10 11Status: Adopted (2007-12-05) 12 13Summary 14------- 15 16OGR has a number of C++ classes that deal with the encoding of style 17information and attaching that to features. More information is 18available in the :ref:`ogr_feature_style` document. 19 20With GDAL/OGR version 1.4.x and older, it was not possible to deal with 21style information using the C API. This RFC proposes the addition of 22functions to the C API to manipulate style information in GDAL/OGR 1.5. 23 24Implementation Details 25---------------------- 26 27- The following enums will be moved from ogr_featurestyle.h to 28 ogr_core.h: 29 30:: 31 32 OGRSTClassId; 33 OGRSTUnitId; 34 OGRSTPenParam; 35 OGRSTBrushParam; 36 OGRSTSymbolParam; 37 OGRSTLabelParam; 38 39- The OGRStyleMgrH (corresponding to the OGRStyleMgr C++ class) will be 40 added to the C API: 41 42:: 43 44 OGRStyleMgrH OGR_SM_Create() 45 void OGR_SM_Destroy(OGRStyleMgrH hSM) 46 47 const char *OGR_SM_InitFromFeature(OGRStyleMgrH hSM) 48 int OGR_SM_InitFromStyleString(const char *pszStyleString) 49 int OGR_SM_GetPartCount(OGRStyleMgrH hSM) 50 OGRStyleToolH OGR_SM_GetPart(OGRStyleMgrH hSM) 51 int OGR_SM_AddPart(OGRStyleMgrH hSM, OGRStyleTool *sPart) 52 53- The OGRStyleToolH (corresponding to the OGRStyleTool C++ class) will 54 be added to the C API: 55 56:: 57 58 OGRStyleToolH OGR_ST_Create(OGRSTClassId eClassId) 59 void OGR_ST_Destroy(OGRStyleToolH hST) 60 OGRSTClassId OGR_ST_GetType(OGRStyleToolH hST) 61 62 OGRSTUnitId OGR_ST_GetUnit(OGRStyleToolH hST) 63 void OGR_ST_SetUnit(OGRStyleToolH hST, OGRSTUnitId eUnit, double dfGroundPaperScale) 64 65 int OGR_ST_GetParamIsNull(OGRStyleToolH hST, int eParam) 66 const char *OGR_ST_GetParamStr(OGRStyleToolH hST, int eParam) 67 int OGR_ST_GetParamNum(OGRStyleToolH hST, int eParam) 68 double OGR_ST_GetParamDbl(OGRStyleToolH hST, int eParam) 69 void OGR_ST_SetParamStr(OGRStyleToolH hST, int eParam, const char *pszParamString) 70 void OGR_ST_SetParamNum(OGRStyleToolH hST, int eParam, int nParam) 71 void OGR_ST_SetParamDbl(OGRStyleToolH hST, int eParam, double dfParam) 72 const char *OGR_ST_GetStyleString(OGRStyleToolH hST) 73 74 int OGR_ST_GetRGBFromString(OGRStyleToolH hST, const char *pszColor, 75 int *nRed, int *nGreen, int *nBlue, int *nAlpha); 76 77Note: at implementation time, the OGR_ST_GetParamIsNull() has been 78removed and replaced by an 'int \*bValueIsNull' argument on all the 79OGR_ST_GetParam...() functions in order to map more closely to the C++ 80methods. 81 82- NO wrappers will be needed for the following C++ classes which are 83 handled internally by the OGR\_ST\_\* wrappers above: 84 85:: 86 87 class OGRStylePen : public OGRStyleTool 88 class OGRStyleBrush : public OGRStyleTool 89 class OGRStyleSymbol : public OGRStyleTool 90 class OGRStyleLabel : public OGRStyleTool 91 92- Note that ogr_featurestyle.h also contains a OGRSTVectorParam enum 93 and a corresponding OGRStyleVector class but this class is currently 94 unused and may eventually be removed, so we will not implement 95 support for it in the C API (and the OGRSTVectorParam enum will NOT 96 be moved to ogr_core.h). 97 98Python and other language bindings 99---------------------------------- 100 101The initial implementation will be for the C API only and will not be 102ported/tested with the Python and other scripting language bindings. 103This will have to wait for a later release. 104 105Implementation 106-------------- 107 108Daniel Morissette will implement the changes to the C API described in 109this RFC for the GDAL/OGR 1.5.0 release. 110 111The first test of the new C API functions will be the conversion of 112MapServer's mapogr.cpp to use them. 113 114Related Ticket(s) 115----------------- 116 117#2061 118 119Voting History 120-------------- 121 122+1 from all PSC members (FrankW, DanielM, HowardB, TamasS, AndreyK) 123