The FieldView program — API documentation

TMC Suite package. A graphical viewer of electromagnetic-field distributions in a two-dimensional area: it builds 2D/3D surfaces and lines of the field distribution, the permittivity (ε) and the block topology using OpenGL. All signatures are taken from the sources in src/fieldview/ and the shared headers from src/Include/.

1. Purpose of the program

FieldView (the output EXE — FieldView.exe; the project file FldView.vcxproj, <TargetName>FieldView</TargetName>) is a graphical viewer of electrodynamic-computation results: it builds 2D/3D visualizations of the field distribution in the computation area, as well as of the permittivity distribution and the block topology.

The program is built on the MFC Document/View (MDI) scheme. Each document is a binary field-distribution file (.ex, the TMC Suite format) that contains the grid parameters and the array of field values. The program can:

• open field-distribution files (.ex) and topology files (.tt);
• build 3D surfaces (GL_TRIANGLES) and 2D maps (GL_QUADS) of the field distribution;
• build lines (GL_LINE_STRIP) of the field distribution by cross-sections;
• display the ε distribution over the topology;
• display the topology (rectangular, circular, polygonal blocks: metal, magnetic, dielectric, inputs, absorbers);
• build the X/Y/Z axes with dimension lines and input numbering;
• rotate the scene (with the mouse and commands, around the X/Y/Z axes);
• translate the scene and the data, scale the view (including along a single axis);
• configure the 20-color palette for the field and ε (auto-interpolation or manual levels);
• configure the Z limits (automatic or manual);
• switch between the 2D and 3D modes separately for the field, ε and topology;
• configure the transparency (blend) of the layers;
• save the display parameters in the registry (the application key, the keys of §5.10);
• track file changes and automatically re-read the data (the timer OnTimer).

Requires OpenGL: opengl32.lib, glu32.lib.

2. Project composition

The composition by FldView.vcxproj (the ClCompile section):

The files TmcRTH_BlockList1.cpp/.h physically lie in the directory but are not included in the project (absent from ClCompile). The header contains the hard-coded path z:\work\source\include\tmcrth_bolcklist.h; the class CTmcRTH_BlockList1 is an empty wrapper over CTmcRTH_BlockList. Dead code.

Dependencies (AdditionalDependencies): opengl32.lib, glu32.lib, sfile95.lib, prepr.lib, exprint.lib, TMCIndan.lib, TMCLibError.lib.

In TmcGLText.h the include <gl\glaux.h> was removed: GLAUX is absent from the modern Windows SDK, the aux* functions are not used in the code (a porting fix, see ISSUES.md, Phase 4).

3. The CFldViewApp class

Purpose: the MFC application class. Header: FldView.h · Base class: CWinApp

BOOL InitInstance()

Initialization: AfxOleInit(), SetRegistryKey(...) (the fix for bug #6 — the CRecentFileList::Add crash without OLE/registry, see ISSUES.md), registering CMultiDocTemplate, creating CMainFrame, reading the MRU, restoring the window position.

Handler: afx_msg void OnAppAbout() — the "About" window.

User messages (defined in FldView.h)

The properties dialogs send these messages to the view; the handlers — §5.9.

4. The CFldViewDoc class — the document

Purpose: reading the binary field data (.ex), storing the array of values, tracking file changes. Header: FldViewDoc.h · Base class: CDocument

4.1. Fields

4.2. Public methods

MFC overrides: OnNewDocument(), Serialize(CArchive&).

4.3. Private methods

5. The CFldViewView class — the view (OpenGL)

Purpose: all the OpenGL drawing, handling user input, storing and saving the display settings. Header: FldViewView.h · Base class: CScrollView Size: FldViewView.cpp ~162 KB — the largest file of the project.

FldViewView.h also declares the global PutTrace/PutStatistics (output to the status bar, as in the kernels).

5.1. OpenGL initialization

Related fields: HGLRC hrc (the OpenGL context), CClientDC *m_pDC, CPalette m_cPalette, CPalette *m_pOldPalette, CRect m_oldRect, float m_fRadius, BOOL m_play.

5.2. Field drawing

5.3. ε drawing

5.4. Topology drawing

5.5. Axes and dimension lines

5.6. Coordinate transformations

5.7. Color management

5.8. Data preparation

5.9. Message handlers

Scene rotation: OnRotateLeft/Right/Top/Bottom, OnRotateLefty/Righty, OnRotatexn/xv, OnRotateyn/yv, OnRotatezn/zv (the angles wAngleX/Y/Z).

Translation: OnTranslateXt/Xb/Yt/Yb/Zt/Zb, OnTranslateXn/Xv/Yn/Yv/Zn/Zv (the values wTranslateX/Y/Z); data translation — OnTranslatedataxn/xv/yn/yv.

Arrows: OnStrelkleft/right/up/down.

Scaling: OnViewZoomP/M (general), OnViewZoomPx/Mx (along X), OnViewZoomPy/My (along Y); OnViewDefault (the default view), OnViewProportionally (the proportional mode, the flag bProportionally).

Field display modes: OnFlagdrawsurface/OnFlagdrawline (surface/lines), OnDimension23switch (2D/3D), OnFieldL/OnFieldValue/OnFieldModul (the quantity type: level/value/magnitude; the flags bDrawFieldValueFlag, bDrawFieldModulFlag).

ε modes: OnFlagdrawsurfaceeps/OnFlagdrawlineeps, OnDimension23switcheps.

Topology modes: OnFlagdrawsurfacetop/OnFlagdrawlinetop, OnDimension23switchtop; the block-type visibility — OnViewTopologyBoundaryEps/Metal/Magnetic/Input/Absorber (the flags bDrawFlagEps/Metal/Magnetic/Input/Absorber).

Dimension lines: OnViewFieldSize, OnViewEpsSize, OnViewTopologyDimensionsAlonganxaxies/Alonganyaxies, OnViewTopologySizeBlock, OnViewTopologySizeLinklist.

Mouse: OnLButtonDown/Up, OnMouseMove (mouse rotation; the fields cMousePoint, bIsMouseLButonDown), OnLButtonDblClk, OnRButtonDown.

Other: OnViewParameters (the properties window §10.1), OnTimer(UINT_PTR nIDEvent) (polling for file change and re-reading), OnDestroy.

Messages from the dialogs:

For most commands there are paired OnUpdate* handlers for the availability/checking of the menu items.

MFC overrides: OnDraw, PreCreateWindow, OnPrepareDC, OnInitialUpdate, OnPreparePrinting, OnBeginPrinting, OnEndPrinting, OnUpdate.

5.10. Key setting fields and save keys

The main groups of private fields:

The settings are saved (WriteIniFile) under the name-constants TMC_GROFLD_*_INI from FldViewView.h — the section #TMC_GraphicsOutputFieldFile, the parameters: DrFl (drawing flags), DrFlSurface, DrFlLine, DrFlAxies, FlXSize/FlYSize/FlZSize, Fl23D, Blend, Xmin/Xmax/Ymin/Ymax/Zmin/Zmax, XAngle/YAngle/ZAngle, XTranslate/YTranslate/ZTranslate, ColorAxies, FontAxies, FontNameAxies, ColorZField, ColorZEps, Dr_FlAxiesSize, Topology, TopologyColor_EpsMetMagInp, PropertyPageNumber, ColorResolution, EpsParam, DrawFieldModulFlag, #INIWND (the window).

6. The CTmcGLText class — OpenGL text

Purpose: outputting text into the OpenGL scene: a string is rendered into a GDI bitmap, which is output by an OpenGL raster operation. Header: TmcGLText.h · Base class: CWnd

Public methods

Private elements

7. The CTmcBlockTpl class — reading the topology

Purpose: reading the topology file (.tt) and the ε(x,y) distribution. Header: TmcBlockTpl.h · Base class: CTmcRTH_BlockList (TMCIndan)

Public methods

Private: void InitAllocationArray(void), void ReadData(void); the fields nTCurrent, dTCurrent, dDelta, dXmin, dYmin, nX, nY, pdSurface (the ε distribution), csTplFileName, cError.

8. The CTmcBoundaryTpl class — the block boundaries

Purpose: the representation of the boundaries of one topology block for drawing the contours and the dimension lines. Header: TmcBoundaryTpl.h — an ordinary C++ class (the inheritance from CWnd is commented out).

Public methods

Private: TranslateX0Y0(), DeleteData(); the fields nInputNum, nTopSize, cTopSizeLinklListX0/Y0, pcTopSize, dX0/dY0, nBlock, csBlock, csEpsExpr, pX1..pX4, pY1..pY4, nPoint, nType.

9. The CTmcTopSize class — a dimension line

Header: TmcTopSize.h · Base class: CWnd

10. Dialogs

10.1. CTMCDialogPropet — the properties window

Base class: CPropertySheet. 4 tabs: "Place" (CTMCDialogPlace), "Field" (CTMCDialogField), "Eps" (CTMCDialogEps), "Topology" (CTMCDialogTopology). On the Apply button the tabs send the view the messages WM_USERAPPLY_PROP* (§3).

10.2. CTMCDialogPlace — the "Place" tab

The X/Y axes, the length/time units, the axis font, proportional display.

10.3. CTMCDialogField — the "Field" tab

The color scale (20 colors), the Z limits (auto/manual), 2D/3D, blend, the displayed quantity type (L / Value / Modul).

10.4. CTMCDialogEps — the "Eps" tab

The ε color scale, the Z limits, 2D/3D, blend.

10.5. CTMCDialogTopology — the "Topology" tab

Block visibility by type (dielectric/metal/magnetic/input/absorber), the colors, surface/lines, 2D/3D.

10.6. CTmcASetColor — palette configuration

Configuring the 20-color palette with auto-interpolation between the reference colors.

10.7. CColorLevelDlg — the color levels

Manual input of 20 values of the color-scale levels; it reports its closing to the view (OnCloseColorLevelDialog).

11. Input file formats

11.1. The binary field file (.ex)

The header markers are the constants TMC_GROFLD_DOCFILE_* from the shared header src/Include/Tmcgrviw.h (lines 101–111):

#TMC_GraphicsOutputFieldFile FormVer2.0 2000
#TMCGROFLD_nT <nT>
#TMCGROFLD_Time <T>
#TMCGROFLD_Delta <Delta>
#TMCGROFLD_Xmin <Xmin>
#TMCGROFLD_Ymin <Ymin>
#TMCGROFLD_Accuracy <Accuracy>
#TMCGROFLD_LongUnit <unit>
#TMCGROFLD_TimeUnit <unit>
#TMCGROFLD_nX <nX>
#TMCGROFLD_nY <nY>
<binary data: nY × nX values>

11.2. The topology file (.tt)

Created by the compute kernel (TMCIndan: csFileNameTopology.Format("%s.tt", ...)). The structure:

#TMC_TopologyOutputFile FormVer2.0 2000
#BlockListBegin
<topology blocks>
#BlockListEnd
<field parameters>
<binary data>

11.3. Topology block types (nType)

The constants from src/Include/Tmcgrviw.h (used by SetColornType):

Additionally, absorber variants CTMCRTH_BLCKNTYPE_ABSR_0000..1111 (values 1–16) and ABSR_1111_1..4 (21–24) are defined — a bit-mask encoding of the absorbing sides.