SDK organization

This section describes the overall organization of the SpeedTree SDK and assumes no prior knowledge of SpeedTree. It is recommended that you read the How to Use This SDK section to gain an understanding of the purpose of the SDK as well as the level of application integration that will best suit your needs.

There are several libraries in the SDK, building upon one another with specializations for each supported graphics API as illustrated below:

• Core: Reads the .stsdk file format, providing coordinates, texcoords, tangents, billboard data, level of detail (LOD) data, materials and texture filenames, bones, and collision objects. Also provides run-time wind management, coordinate system conversions, and a client callback system (allocations, file access).

• Forest: Dependent on Core, the Forest library handles the management of dynamic forests containing potentially millions of trees. It houses optimized culling and LOD systems in addition to a dynamic grass/undergrowth system great for rapid prototyping. Like the Core library, Forest has no graphics API dependencies.

• Render Interface: Dependent on Forest, the Render Interface library makes abstract graphics calls to efficiently render the forest, complete with shader loads, texture loads and binds, state changes, efficient vertex buffer rendering, shadows, lighting, and more. The Render Interface library makes calls to empty graphics wrappers, to be populated by the next libraries.

• Rendering Classes: Dependent on Render Interface, the rendering classes contain platform-specific graphics implementations, filling out the graphics interfaces defined by the Render Interface library. Populating the abstract interfaces is all that is required to adopt a new graphics API. Interface classes include those that manage textures, shaders, shader constants, vertex/index buffer objects, and render state changes.

The SDK ships with a demonstration application called the Reference Application. The Reference Application is a standalone program that shows how a deep integration might be handled, though each user's integration will vary according to their goals and requirements. The SpeedTree team uses this application to test the stages of the SpeedTree games pipeline.

At its most basic level, the SpeedTree SDK is organized like many other SDK or middleware offerings. You'll need to be able to include the SDK header files, link to its libraries and, in the case of DLLs, make sure that the correct DLL(s) are in your binary path or copied next to your application's executable. Static libraries are also included.

In a default installation (file system location notated here as [SDK]/), the key SDK files needed for integration are located as noted below:

• Include Files: Modify your include path to contain [SDK]/Include/.

• Library Files: Modify your library path to contain [SDK]/Lib/[PLATFORM]. [PLATFORM] may be anything from Windows/VS2022.x64/ to Orbis/ or 360/.

• Binary Files: To harness the SpeedTree binaries (unless you're using the static libraries) under Windows you should either add [SDK]/Bin/[PLATFORM] to your path variable or copy the needed DLLs into the same folder as your application's executable. Which DLLs you'll need depends on your level of integration.

Each LIB and DLL file is named descriptively to avoid mixing up the wrong versions. The naming structure is as follows:

SpeedTree<lib base name>_<version>_<build type>_<runtime library>[_Static][_d]

This results in names such as SpeedTreeCore_Windows_v9.1.1_VS2022_MT64_Static, or SpeedTreeCore_PS5_v9.1.1_Static_d.a, etc. There are quite a few libraries and DLLs to chose from in the SDK, but hopefully this naming policy will prevent headaches in finding the correct version for your needs.

Note: If using the DLL versions of the SpeedTree libraries, be sure to #define ST_USE_SDK_AS_DLLS in the client application.

The SpeedTree SDK includes versioning hints to help runtime configuration and usage. The ST_VERSION_STRING macro contains a string version number (for example, “9.1.1”), and ST_VERSION_MAJOR, ST_VERSION_MINOR, and ST_VERSION_SUBMINOR contain the numerical values. These macros can be checked at any point to determine the version of the SpeedTree SDK being used.

To avoid mismatches between header files and libraries, the static CCore::Version() function can be used. CCore::Version() returns a long descriptive string about the build type, platform, and version used when building the library. Or, passing true in the bShort parameter to CCore::Version() returns a string that can be directly compared to the ST_VERSION_STRING define to determine if the header and library match.

All of the source code contained in the SDK libraries is housed in the SpeedTree namespace. Use this namespace to resolve any conflicts between SDK types and your own.