File: naming_engine_3.0.txt

package info (click to toggle)
castle-game-engine 5.2.0-3
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 185,428 kB
  • sloc: pascal: 260,781; cpp: 1,363; objc: 713; makefile: 537; xml: 496; sh: 480; php: 4
file content (329 lines) | stat: -rw-r--r-- 16,489 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
With engine release 3.0, we renamed "Kambi VRML game engine"
to "Castle Game Engine". We want to break compatibility anyway,
so I decided to do a large rename of many units and classes,
to make names more consistent, more sensible etc. This document
summarizes renames done, and some reasoning.

------------------------------------------------------------------------------
1. Ideas, reasoning:

- We don't want Kambi, Kam prefix to anything (units, classes).
  Instead use CastleXxx for units, TCastleXxx for classes,
  but *only if necessary* (preferably, avoid prefixing everything,
  to keep names simple). Don't shorten Castle to Cas or Ca for prefix
  --- instead, avoid this prefix altogether where possible.

  Components should all have TCastleXxx prefix (to not clash with
  other components, this would make our engine conflict with other
  packages you have installed in Lazarus).
  Exceptions: TXxxCamera for TCamera descendants.

  Units with common names (XxxUtils, XxxWarnings) may have Castle prefix,
  to avoid clashes with common units.

- We don't want VRML prefix to anything (units, classes).
  VRML is old (that's why we rename engine after all).
  Instead use X3D, but *only if necessary* (preferably, avoid any X3D prefix,
  the engine is directed at X3D anyway --- it's known that "a node"
  means "a VRML/X3D node" inside the engine).

  E.g. TVRMLGLScene becomes just TCastleScene. No need to emphasize "VRML"
  or "X3D" in the name, since actually this is used to handle any 3D models
  (even if others are converted to VRML/X3D node graph under the hood...
  but this is implementation detail, not interesting to everyone.)

  Guideline: things that are *conceptually* not tied to VRML or X3D (even if their
  current and only implementation is tied to VRML/X3D nodes graph) should *not* have
  VRML/X3D in their names.

- We don't want to add GL or OpenGL to classes (except really low-level
  stuff, that is used only by programmers who understand OpenGL).
  Reasoning: 1. our engine is directed 100% now for OpenGL
  (so e.g. TVRMLGLScene is actually "the thing you use to render 3D models",
  and most programmers are not interested in emphasizing that it's for OpenGL),
  2. if some day we will have alternative renderer, it should be pluggable,
  and the same class names should be usable with it.

  So things that are *conceptually* not tied to OpenGL (even if their
  current and only implementation is tied to OpenGL) should *not* have GL
  in their names. Only things that have API specifically for OpenGL cooperation
  (like CastleGLUtils, or GLImages, or TGLRenderToTexture) may keep
  "GL" inside name.

  This also avoids clashes with GLScene, that uses a TGLXxx for various
  class names and GLXxx for various units.
  And component names should not clash across packages
  (this would make it difficult to install both GLScene and our engine
  in Lazarus; we don't want to cause such trouble).

  For engine developers, the directory layout in the engine strictly separates
  things dependent on OpenGL from others (opengl/ subdirs).

- Make 2D controls (TUIControl descendants) have consistent names.
  (Currently, some are TKamGLXxx, some TKamXxx, some TGLXxx.)
  New name for all is TCastleXxx (following above reasons to drop GL and Kam
  prefixes).

  So e.g. TKamSceneManager becomes... not TVRMLSceneManager,
  not TX3DSceneManager, but TCastleSceneManager.

- Make 3D objects (T3D descendants) have consistent names.
  This is actually started: T3DXxx prefix is nice (they are also
  components, so some prefix is needed), already: T3D, T3DList, T3DTranslated.
  Use it consistently, and (following above ideas) do not add
  additional "VRML", "X3D", "GL", "Kam" etc. prefixes to the name.

  For components, we have to use TCastleXxx prefix (since otherwise
  Lazarus gives by default a name that isn't a valid identifier,
  http://lists.lazarus.freepascal.org/pipermail/lazarus/2011-October/067797.html).
  So e.g. TVRMLGLScene becomes just TCastleScene.

------------------------------------------------------------------------------
2. Renames done, identifiers inside units:

- VRML/X3D node classes renamed to TXxxNode or TAbstractXxxNode.
  Motivation: remove TVRML prefix, unify own and X3D spec abstract classes naming (no need to differentiate them by name), move Node to the end (more English-like).
  * TNodeXxx -> TXxxNode
  * TNodeX3DXxxNode -> TAbstractXxxNode
  * TVRMLXxx -> either TX3DXxx (special) or TAbstractXxxNode (abstract)

- Window/control renames:
  * TGLWindowXxx -> TCastleWindowXxx, also changing suffixes:
    TGLWindow -> TCastleWindowBase,
    TGLWindowVRMLBrowser -> TCastleWindow, and so on.
    TCastleWindow is now the final (with SceneManager ready) class, and this is advised to be used in new programs.
  * TKamVRMLBrowser -> TCastleControl, this is advised to be used with Lazarus.
    TKamOpenGLControl -> TCastleControlXxx.
- Components and important classes renames:
  * 2D controls to TCastleXxx, like TCastleButton and TCastleImage and TCastleSceneManager.
  * 3D also to TCastleXxx: TCastlePrecalculatedAnimation, TCastleScene
  * TVRMLShape -> TShape
    TVRMLTriangle -> TTriangle, and so on.

- Precisely:
tkamopenglcontrolcore  TCastleControlBase
tkamvrmlbrowser        TCastleControl
tkamopenglcontrol      TCastleControlCustom
tglwindowstate         TWindowState
tglwindowparseoption   TWindowParseOption
tglwindowparseoptions  TWindowParseOptions
pglwindowparseoptions  PWindowParseOptions
tglwindowmessagetype   TWindowMessageType
tglwindowfunc          TWindowFunc
tglwindowcallbacks     TWindowCallbacks
tglwindowlist          TWindowList
tglwindowdemo          TCastleWindowDemo
tgluiwindow            TCastleWindowCustom
tglwindowvrmlbrowser   TCastleWindow
tglwindow              TCastleWindowBase
tkamrecentfiles        TLazRecentFiles
tglrecentfiles         TCastleRecentFiles
tkamglbutton           TCastleButton
tkamglimage            TCastleImageControl
tglnotifications       TCastleNotifications
tglmenu                TCastleOnScreenMenu
tkamxmlconfig          TCastleConfig
tkamscenemanager       TCastleSceneManager
tvrmlanimation         TCastlePrecalculatedAnimationCore
tvrmlglanimation       TCastlePrecalculatedAnimation
tvrmlscenespatialstructure  TSceneSpatialStructure
tvrmlscenegeometrychanged   TSceneGeometryChanged
tvrmlscenenotification      TSceneNotification
tvrmlscenefreeresource      TSceneFreeResource
tvrmlscenevalidit           TSceneValidit
tvrmlscenerenderingattributes TSceneRenderingAttributes
tvrmlscene             TCastleSceneCore
tvrmlglscene           TCastleScene
tvrmlshape             TShape
tvrmlglshape           TGLShape
tvrmltriangle          TTriangle
pvrmltriangle          PTriangle
tvrmlbasetrianglesoctree            TBaseTrianglesOctree
tvrmlshapeoctree                    TShapeOctree
tvrmltriangleoctree                 TTriangleOctree
tvrmlbasetrianglesoctreenode        TBaseTrianglesOctreeNode
tvrmlshapeoctreenode                TShapeOctreeNode
tvrmlwireframeeffect                TWireframeEffect
tglmenuitemaccessory       TMenuAccessory
tglmenuitemargument        TMenuArgument
tglmenubooleanargument     TMenuBooleanArgument
tglmenuslider              TMenuSlider
tglmenufloatslider         TMenuFloatSlider
tglmenuintegerslider       TMenuIntegerSlider
TGLMenuVolumeSlider TCastleMenuVolumeSlider
TKamTime TFloatTime
TVRMLTime TX3DTime
KamTimer Timer
tkamglfontcontrol TUIControlFont
tkambuttonimagelayout TCastleButtonImageLayout
tkampanel TCastlePanel
KamScript CasScript
KambiOSCheck OSCheck
TVRMLChange TX3DChange
TVRMLKeyword TX3DKeyword
TVRMLVersion TX3DVersion

tvrmlaccesstype                             TX3DAccessType
tvrmlaccesstypes                            TX3DAccessTypes
tvrmlbindablestack                          TX3DBindableStack
tvrmlbindablestackbasic                     TX3DBindableStackBasic
tvrmlcameraversion                          TX3DCameraVersion
tvrmlchange                                 TX3DChange
tvrmlchanges                                TX3DChanges
tvrmlevent                                  TX3DEvent
tvrmleventlist                              TX3DEventList
tvrmleventreceive                           TX3DEventReceive
tvrmleventreceivelist                       TX3DEventReceiveList
tvrmleventsengine                           TX3DEventsEngine
tvrmleventsenginelist                       TX3DEventsEngineList
tvrmlexport                                 TX3DExport
tvrmlexternalprototype                      TX3DExternalPrototype
tvrmlfield                                  TX3DField
tvrmlfieldclass                             TX3DFieldClass
tvrmlfieldlist                              TX3DFieldList
tvrmlfieldorevent                           TX3DFieldOrEvent
tvrmlfieldoreventlist                       TX3DFieldOrEventList
tvrmlfileitem                               TX3DFileItem
tvrmlfileitemlist                           TX3DFileItemList
tvrmlfontfamily                             TX3DFontFamily
tvrmlfontjustify                            TX3DFontJustify
tvrmlglslprogram                            TX3DGLSLProgram
tvrmlgraphtraversestate                     TX3DGraphTraverseState
tvrmlgraphtraversestatestack                TX3DGraphTraverseStateStack
tvrmlimport                                 TX3DImport
tvrmlimportablenames                        TX3DImportableNames
tvrmlinterfacedeclaration                   TX3DInterfaceDeclaration
tvrmlinterfacedeclarationlist               TX3DInterfaceDeclarationList
tvrmlkeyword                                TX3DKeyword
tvrmlkeywords                               TX3DKeywords
tvrmlmaterialinfo                           TX3DMaterialInfo
tvrmlmaterialinfoabstract                   TX3DMaterialInfoAbstract
tvrmlmaterialinfo_1                         TX3DMaterialInfo_1
tvrmlmultfield                              TX3DMultField
tvrmlnames                                  TX3DNames
tvrmloctreeignoreforshadowraysandoneitem    TOctreeIgnoreForShadowRaysAndOneItem
tvrmlprototype                              TX3DPrototype
tvrmlprototypebase                          TX3DPrototypeBase
tvrmlprototypebaselist                      TX3DPrototypeBaseList
tvrmlprototypenames                         TX3DPrototypeNames
tvrmlrenderershape                          TX3DRendererShape
tvrmlrenderingattributes                    TRenderingAttributes
tvrmlrenderingattributesclass               TRenderingAttributesClass
tvrmlroute                                  TX3DRoute
tvrmlroutelist                              TX3DRouteList
tvrmlsimplemultfield                        TX3DSimpleMultField
tvrmlsinglefield                            TX3DSingleField
tvrmlsinglefieldclass                       TX3DSingleFieldClass
tvrmlsinglefieldlist                        TX3DSingleFieldList
tvrmltoken                                  TX3DToken
tvrmltokens                                 TX3DTokens
tvrmlviewpointclassnode                     TX3DViewpointClassNode
tkamabstractviewport                        TCastleAbstractViewport
tkamabstractviewportlist                    TCastleAbstractViewportList
tkamobjectlist                              TCastleObjectList
tkamobjectqueue                             TCastleObjectQueue
tkamobjectstack                             TCastleObjectStack
tkamstringlist                              TCastleStringList
tkamviewport                                TCastleViewport
loadfromvrmlevents                                LoadFromEvents
KamCoTan                 CastleCoTan
KamDivMod                CastleDivMod
KamGLPolygonStipple      CastleGLPolygonStipple
KamGluSphere             CastleGluSphere
KamGL_CLAMP_TO_EDGE      CastleGL_CLAMP_TO_EDGE
KamReadLink              CastleReadLink
LoadVRMLClassic LoadX3DClassic
loadvrml Load3D
savevrml Save3D
EVRML EX3D

------------------------------------------------------------------------------
3. Renames done, unit names:

- Unit Object3DAsVRML -> X3DLoad, with various X3DLoadInternal* helper units.
- "The Castle" game units renamed CastleXxx -> GameXxx.
  Motivation: do not clash with engine units.
- KambiXxx units renamed to CastleXxx (following engine rename)

- Precisely:
kambiogg                               castleogg
kambiopenal                            castleopenal
kambiurlutils                          castleurlutils
kambipng                               castlepng
kambipropedits                         castlepropedits
kambiglcontrol                         castlecontrol
kambilclutils                          castlelclutils
kambiglutils                           castleglutils
kambiglut                              castleglut
kambixf86vmode                         castlexf86vmode
kambiglx                               castleglx
kambitimeutils                         castletimeutils
kambistringutils                       castlestringutils
kambiwarnings                          castlewarnings
kambidynlib                            castledynlib
kambiclassutils                        castleclassutils
kambiinterfaces                        castleinterfaces
kambixmlconfig                         castlexmlconfig
kambixmlutils                          castlexmlutils
kambiparameters                        castleparameters
kambizstream                           castlezstream
kambilog                               castlelog
kambiutils                             castleutils
kambifilesutils                        castlefilesutils
kambizlib                              castlezlib
kambiscenemanager                      castlescenemanager
kambiscriptcorefunctions               castlescriptcorefunctions
kambiscriptimages                      castlescriptimages
kambiscript                            castlescript
kambiscriptparser                      castlescriptparser
kambiscriptarrays                      castlescriptarrays
kambiscriptvectors                     castlescriptvectors
kambiscriptlexer                       castlescriptlexer
testkambistringutils                   testcastlestringutils
testkambiscriptvectors                 testcastlescriptvectors
testkambiclassutils                    testcastleclassutils
testkambiscript                        testcastlescript
vrmlkambiscript                        x3dcastlescript
kambioctree                            CastleOctree

glwinmodes                 windowmodes
glwindow                   castlewindow
glwinmessages              castlemessages
glsoundmenu                castlesoundmenu
glprogress                 castleprogress
glwindowrecentfiles        castlerecentfiles
glwininputs                castleinputs

vrmltriangle                                       triangle
vrmlglscene                                        castlescene
vrmlshape                                          shape
vrmltime                                           x3dtime
vrmltriangleoctree                                 triangleoctree
vrmlfields                                         x3dfields
vrmlscenewaypoints                                 scenewaypoints
vrmlnodesdetailoptions                             x3dnodesdetailoptions
vrmllexer                                          x3dlexer
vrmlglbackground                            background
vrmlglrendererlights                        glrendererlights
vrmlglrenderer                              glrenderer
vrmlglanimation                             precalculatedanimation
vrmlglrenderertextureenv                    glrenderertextureenv
vrmlshader                                  glrenderershader
vrmlanimation                                      precalculatedanimationcore
vrmlshadowmaps                                     x3dshadowmaps
vrmlarraysgenerator                                arraysgenerator
vrmlcamerautils                                    x3dcamerautils
vrmlraytracer                                      raytracer
vrmlnodes                                          x3dnodes
vrmllighting                                       lighting
vrmlshapeoctree                                    shapeoctree
vrmlscene                                          castlescenecore
glnotifications CastleNotifications
glcontrols CastleControls
glmenu OnScreenMenu

------------------------------------------------------------------------------
4. Renames done, package names:

Lazarus package names have to change too. Now we have
castle_base, castle_components, castle_window.