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