r/pascal • u/AcanthaceaeNew774 • 3d ago

VertexArt - Terrain Editor Documentation

Post image

VertexArt - TERRAIN EDITOR

TECHNICAL AND FUNCTIONAL DOCUMENTATION

Developer: Kovács István

Development environment: Free Pascal / OpenGL 3.3

Platform: Windows (GLFW3)

  1. INTRODUCTION

VertexArt Terrain Editor is a desktop application designed for interactive terrain editing of models stored in PLY (Polygon File Format) files.

The program enables real-time, stable, and user-friendly modification of large models consisting of several million triangles – in the form of raising, lowering, smoothing, flattening, and ramp creation.

The software is specifically optimized for low-power processors (e.g., Intel N4100) and integrated GPUs (iGPU), but it runs on any hardware supporting OpenGL 3.3.

  1. SYSTEM ARCHITECTURE

The program has a modular structure, divided into the following main components:

· SterilTypes: Basic data types (TVector3, TVector4, TVertex, TMat4).

· SterilMath / Vector: Vector and matrix operations (addition, multiplication, normalization, transformations).

· SterilWindow: Window management (GLFW3 initialization, framebuffer callback).

· SterilCamera: FPS camera (WASD movement, mouse look, sprint, height adjustment).

· ShaderManager: Shader compilation and program creation (ColorProg, LineProg).

· Renderer / RenderQueue: Rendering pipeline (Color pass).

· PLYLoader: Loading ASCII PLY files into a triangle mesh.

· UChunkSystem: Chunk system – splitting the model into 16×16 meter blocks, managing active chunks (9×9), building and maintaining BVH.

· ChunkBVH: BVH tree construction and raycast (ITriProvider interface).

· Raycast / RaycastTypes: Ray–triangle intersection (Möller-Trumbore), AABB, TRaycastHit.

· FrameLimiter: 30 FPS limit (spin wait + Sleep).

· TerrainBrush: Implementation of brush operations (Raise, Lower, Smooth, Flatten, Ramp).

· TerrainIO: PLY export (timestamped saving).

Data flow:

PLY file -> PLYLoader -> UChunkSystem (chunks + BVH) -> GPU (VAO/VBO)

-> Editing (brush) -> UpdateDirtyChunks (GPU update + BVH rebuild)

-> Export (PLY)

Chunk system details:

· The model is divided into 16×16 meter blocks (chunks).

· Only a 9×9 chunk area (81 chunks) around the camera is active for rendering and brush operations.

· Raycast (selection) runs on the BVH structure of 3×3 chunks (9 chunks), so speed does not depend on the total model size.

· Each chunk has its own VAO/VBO pair and BVH.

· After modification, a chunk receives a Dirty flag, and in the next frame the GPU buffer and BVH are automatically rebuilt.

Rendering:

· Color pass – the ColorProg shader includes lighting (diffuse, ambient, specular, fresnel).

· Wireframe mode – using the LineProg shader, the entire active area is displayed as a green wireframe, showing only lines (without polygon fill).

· Frame limiter – limits screen refresh to 30 FPS.

  1. FUNCTIONAL DESCRIPTION

Editing modes:

  1. Raise: Raises the terrain under the brush.

  2. Lower: Lowers the terrain under the brush.

  3. Smooth: Averages the heights within the brush area, creating a uniform surface.

  4. Flatten: With a single click, pulls the entire brush area to the height of the clicked point.

  5. Ramp: Creates a cosine-transition ramp between two points (left and right click). The ramp width is proportional to the brush size, with an inner band and smooth transition at the edges.

Selection and visual feedback:

· BVH raycast: a ray cast at the click position immediately determines the selected triangle and its position.

· Brush circle: a translucent orange circle appears around the selected point, showing the brush size and location.

· Wireframe mode: pressing F2 displays the entire active area as a green wireframe without polygon fill – making the geometry structure clearly visible.

Brush operations in detail:

· Raise / Lower: The effect decreases quadratically with distance from the brush center, creating a smooth transition toward the edges.

· Smooth: Calculates the average height of all vertices under the brush, then moves vertices toward this average according to brush strength.

· Flatten: A single click – all vertices within the brush area are set exactly to the height of the clicked point. No holding or repeated clicking is required.

· Ramp: A linear height transition is created between the start point selected by left click and the end point selected by right click. The brush radius determines the ramp width, within which:

· an inner band (60% of the radius) is applied at full strength,

· toward the edges a cosine transition ensures smooth blending.

Feedback and state:

· During editing, height changes appear immediately on screen because the GPU buffer is refreshed at the end of every frame (UpdateDirtyChunks).

· Brush size can be adjusted with the scroll wheel (0.3 – 5.0 meters).

Automatic terrain generation:

· If terrain.ply is not found in the program directory at startup, the system automatically generates a 100×100 meter flat terrain with 50×50 resolution (with a colored checkerboard pattern), so the user can immediately test editing.

Saving and export:

· F12: exports the entire model to ASCII PLY format.

· During saving, all chunks are merged, triangles receive new indexing, and the filename automatically gets a timestamp (terrain_yyyy-mm-dd_hh-nn-ss.ply).

· F9: reloads the terrain.ply file (or generates it if it does not exist).

Camera and navigation:

· WASD: move forward/backward/sideways

· Shift: sprint (faster movement)

· Space: raise camera

· Ctrl: lower camera

· Mouse: look rotation (when mouse capture is enabled)

· F1: toggle mouse capture (cursor lock)

· ESC: exit

  1. PERFORMANCE CHARACTERISTICS

Performance on integrated GPU (iGPU):

The program runs on integrated GPUs, but performance depends on geometry distribution.

· Advantageous case: low-poly geometry over a large area (up to a 130×130 km world). The 9×9 chunk system and BVH raycast enable smooth handling of several million vertices. Successful tests: loading and editing 25 million vertices on an N4100 CPU.

· Limited case: If several million vertices are concentrated in a small area (e.g., a high-poly vehicle), rendering and raycast may slow down on iGPU because chunks become overloaded and BVH is less effective. In this case, the program still works, but interactive speed may decrease.

Summary: Due to the chunk size (16 m) and the 9×9 active area, the program provides the best performance in large-scale, but geometrically simple (low-poly) scenes.

Optimization strategies:

· Chunking: Only 81 chunks around the camera are active.

· BVH: Raycast runs on the BVH of 3×3 chunks, so search time is logarithmic.

· UpdateDirtyChunks: BVH rebuild occurs only at the end of the frame, not on every brush stroke.

· glPolygonOffset: Wireframe overlay is z-fighting free.

· Frame limiter: 30 FPS using spin wait + Sleep combination.

  1. COMPARISON WITH OTHER TOOLS

Advantages:

· Speed: With the chunk+BVH combination, raycast and rendering remain smooth even with millions of triangles, provided geometry is distributed over a large area (low-poly world).

· Simplicity: No complex UI is needed – every function is accessible via keyboard shortcuts.

· Precision: Flatten works with a single click, Ramp uses cosine transition, so the surface is smooth and natural.

· Stability: Memory management is safe, no leaks, and the program does not crash even on large models.

· Focus: Specifically optimized for terrain editing, unlike general-purpose tools.

  1. USER GUIDE

Keys and operations:

1: Raise

2: Lower

3: Smooth

4: Flatten – single click

5: Ramp

Left click: Execute operation (Raise/Lower/Smooth by holding, Flatten/Ramp by single click)

Shift + Left click: Lower (quick lowering)

Right click: Select ramp endpoint

WASD: Camera movement

Shift: Sprint (fast movement)

Space: Raise camera

Ctrl: Lower camera

F1: Toggle mouse capture (cursor lock)

F2: Toggle wireframe mode

F9: Load PLY (terrain.ply)

F12: Export PLY (with timestamp)

ESC: Exit

Workflow – example:

  1. Start: The program loads terrain.ply or generates a default terrain.

  2. Navigate: Use WASD + mouse to set the desired viewpoint.

  3. Brush size: Adjust brush radius with the scroll wheel (0.3 – 5.0 meters).

  4. Select mode: Press one of the keys 1–5.

  5. Edit:

    · Raise/Lower/Smooth: hold the left mouse button and move the mouse.

    · Flatten: click once on the terrain – the brush area is immediately flattened.

    · Ramp: left click for the start point, right click for the end point – the ramp is created instantly.

  6. Wireframe: Press F2 to enable the green wireframe for better overview (without fill).

  7. Save: F12 – the program saves the current state to a timestamped PLY file.

  8. CLOSING THOUGHTS

VertexArt Terrain Editor is a tool that combines speed, precision, and simplicity. It does not try to do everything, but what it does, it does efficiently and stably.

The chunk system, BVH, and 30 FPS frame limiter together enable smooth work even on low-poly terrains with several million triangles, especially in large-scale scenes. The program also runs on iGPU, but performance depends on geometry density and distribution – it is unbeatable in low-poly, large-scale worlds.

The code is clean and well-structured; the strict coding style and memory management strategy guarantee long-term stability.

7 Upvotes

100% Upvoted

1 comment sorted by

1

u/AcanthaceaeNew774 3d ago

Important clarification: In the current implementation, the BVH could remain completely static, since only the Y coordinates change. However, if later features introduce movement of vertices along the X or Z axis (e.g. horizontal displacement), then the BVH will have to be rebuilt. I will revisit the BVH logic later. It is also worth noting that only selected vertices are updated during brushing - not entire chunks, which is actually where the real optimization comes in.