API Documentation

[Krishty]

Here’s the first bit of documentation for the API: http://krishty.com/uaw/docs/extensions/

Includes a Visual C++ project for an empty extension.

I’ll extend this step by step to cover the creation of new terrain and new planes.

Note: It would be best practice to add all sample codes to our repository and to its build script. This would guarantee that we immediately notice our samples breaking if we change an important detail, and are reminded to update the documentation. For easy accessibility, however, the samples use Visual Studio solutions instead of my home-brew build system. Building them would drag VS into our repository, which I tried to avoid at all cost. So I suppose if they break, they break 🤷

[mikew]

Nice. Let the fun begin...

[mikew]

Finally, the stars aligned so that I had a Windows PC with VS and some time to try out your example...
..and it didn't work first time with a crash after a second or so. Might be because I might have last run 'build.cmd' before I installed VS2022, so ninja used the VS2019 toolchain and it was incompatible with the extension built with VS2022.
Whatever...it works now.

[Krishty]

Fantastic!

I’m afraid I still haven’t finished the terrain sample, but I’ve done the groundwork by adding two new paragraphs Context-Dependent Interface and Passing Data as well as the chapter Enumerating Content. The latter is a big mess but it should show where the journey will go …

[Krishty]

Terrain not done, but it’s far enough for it to show up in the scenario selection. There’s also a new downloadable sample project.

There’s three new chapters. Sorry for so many words before so little code, but it’s the only dedicated technical documentation we have, so all the concepts should be explained.

• 2.1 Basic Terrain Concepts
• 2.2 The UAW_Extension_Terrain Interface
• 2.3 Enumerating Terrain

Download is in the last chapter.

Be sure to have pulled the latest source code version!

I changed a few file names of the documentation to have it manageable better.

[mikew]

Be sure to have pulled the latest source code version!

That needed more exclamation marks.
I missed that step and it didn't go well...

[Krishty]

Sorry!

Lots of work were required to make it work to this point. I invested a lot into the vehicle API, being under the assumption that new planes would be the most urgent thing to add. The terrain API didn’t get this love, and it really showed when I wrote the documentation …

More changes to come with the next chapter, but hopefully only to the stuff the documentation hasn’t touched yet.

[mikew]

If it's easier to document the plane API stuff first then go ahead with that.

I've been looking through 'UAW API.h' and I think I need to go on a programming course.
As far as I know, I've never written a 'callback' function...

[Krishty]

It just means the engine will call that function, not you. Like someone else is writing the main() and you only provide a set functions that both of you agreed on earlier.

Won’t switch to planes now; almost through …

[Krishty]

I've been looking through 'UAW API.h'

That’s great btw! All EF2000/TAW/AC3 stuff has been done through the interfaces in this one file. Everything you can do, you find there.

Sorry for some places being so messy, as you can see with recent commits, I try to make it easier to understand.

[mikew]

Understanding is definitely going to be the problem as even though your C++ code has the best comments I've ever seen, I struggle with that language in particular and just fixate on things like line 67 where you have:
struct UAW_float_XYZ
where everything else looks like it should be in the format
struct UAW_XYZ_float
Maybe that's used somewhere else though.

[Krishty]

Understanding is definitely going to be the problem as even though your C++ code has the best comments I've ever seen, I struggle with that language in particular and just fixate on things like line 67 where you have:
struct UAW_float_XYZ
where everything else looks like it should be in the format
struct UAW_XYZ_float
Maybe that's used somewhere else though.

Oh, that is definitely an oversight. I wanted to rename it UAW_XYZ_float multiple times, but I always had something more important to do. Yes, it is used more than 100 times in TFXplorer’s internals, but I will definitely rename it 👍

(And so can you; a search+replace on the whole source code should not break anything I guess)

UAW_XYZ_int will be replaced with floating-point numbers, too. This fixed-point stuff is cumbersome, hard to document, and very susceptible to errors …

The quaternions will likely be replaced with Euler angles or three axes. But this doesn’t concern the terrain, so I postpone it.

[mikew]

Sorry, I need to ask something trivial...

I'd like to expand your example with the orange 1-pixel texture in the 'Rendering Terrain' section by having the colour of a particular tile based on information loaded from disk.
So, say we have this 200x200 bitmap from TFX, which is in .bmp format right now, but I can create 2 files, with 1024 bytes for the palette and 40000 bytes for the bitmap.

col_s.png (8.46 KiB) Viewed 5804 times

Based on the north/east coordinates of the tile I'm on, it should be easy to calculate the tile colour, but in which function should I load in the files from disk into buffers so that I only need to do it once?

[Krishty]

but in which function should I load in the files from disk into buffers so that I only need to do it once?

That should be loadTerrain(), which is called only once when the terrain is created. Store the data in the UAW_Extension_Terrain structure and you will have access to it in both creating individual tiles and rendering the whole thing 🙂

[mikew]

Thanks!
It's how individual tiles are defined/handled I'm having trouble understanding. The example with the 256x256 pixel repeated texture seems to allow an infinite map...or at least I can scroll to thousands of tiles in North and east directions in Explorer mode.

[Krishty]

That’s correct – it just keeps creating whatever tile is requested. In your case, loadTerrainTileAt() would do

Code: Select all

if(indexNorth >= 200 || indexEast >= 200)
    return nullptr; // out of bounds; no tile here

[Krishty]

I updated the docs to account for the latest API changes. A parameter changed from void * to UAW_Extension_Scenario, which should make things more clear. The parameter was not used in any of the samples, but existing code needs to be adjusted.

See the changelog for the two pieces of code that must be changed.

And sorry for that. One more parameter will change in the future and then we’re stable.

[Krishty]

That one parameter has now landed. Please check the changelog for instructions.

[mikew]

Thanks to chatGPT, I was (after a couple of hours tracking down some trivial syntax errors) able to replace the generated texture with something loaded in from disk, Next I need to try to make different tiles, so it's not the same tile repeated. That requires a struct of structs I suppose.

gonewrong.PNG (406.64 KiB) Viewed 5365 times

Ok, the colours aren't quite the same as my earlier picture, but the shape is sort of there..

[Krishty]

Excellent 🚀

Next I need to try to make different tiles, so it's not the same tile repeated. That requires a struct of structs I suppose.

Do you have one texture file per tile on disk? In that case, move the data from UAW_Extension_Terrain to UAW_Extension_TerrainTile and move your loading code from loadTerrain() to loadTerrainTileAt().

Otherwise, if all data comes from one huge file, struct of structs sounds right.