vsgXchange

Utility library for converting 3rd party images, models and fonts formats to/from VulkanSceneGraph

Provides builtin support for:

vsgXchange contains source code that can directly read a range of 3d model, shader and image formats.

• reading KTX, DDS, JPEG, PNG, GIF, BMP, TGA and PSD image formats as vsg::Data objects.
• reading GLSL shader files as vsg::ShaderStage objects.
• reading and writing SPIRV shader files as vsg::ShaderModule.
• reading glTF 3d files, both .gltf and .glb supported.
• reading 3D Tiles 1.0 databases
• reading .json files as vsg meta data.
• writing vsg::Object of all types to .cpp source files that can be directly compiled into applications.

Optional support:

cmake automatically finds which dependencies are available and builds the appropriate components:

• reading font formats TrueType etc. using Freetype as vsg::Font.
• reading image & DEM formats .exr using OpenEXR, and GeoTiff etc. using GDAL as vsg::Data.
• reading 3d model formats GLTF, OBJ, 3DS, LWO etc. using Assimp as vsg::Node.
• reading data over the internet reading image and model files from http:// and https:// using libcurl
• reading image and 3d model formats OpenSceneGraph, OpenFlight etc. using osg2vsg/OpenSceneGraph.

Required dependencies:

• VulkanSDK
• VulkanSceneGraph
• CMake minimum version 3.7
• C++17 capable compiler

Optional dependencies:

• libcurl
• Freetype
• ktx : vcpkg install ktx[vulkan]
• draco - used by the vsgXchange::gltf loader to support draco compressed mesh data.
• Assimp, Assimp on github
• OpenEXP
• GDAL
• osg2vsg

Building vsgXchange:

Unix:

In source build:

cmake .
make -j 8
sudo make install

Windows:

Using cmake:

mkdir build && cd build
cmake ..
cmake --build .

How to use vsgXchange in your own applications

CMake additions:

find_package(vsgXchange)

target_link_libraries(myapplication vsgXchange::vsgXchange)

C++ additions:

#include <vsgXchange/all.h>

...

// assign a composite ReaderWriter that includes all supported formats
auto options = vsg::Options::create(vsgXchange::all::create());

// pass in the options that provide the link to the ReaderWriter of interest.
auto object = vsg::read("myimage.dds", options);

// read file and cast to vsg::Data if possible, returns vsg::ref_ptr<vsg::Data>
auto image = vsg::read_cast<vsg::Data>("myimage.dds", options);

// read file and cast to vsg::Node if possible, returns vsg::ref_ptr<vsg::Node>
auto model = vsg::read_cast<vsg::Node>("mymodel.gltf", options);

// write file
vsg::write(model, "mymodel.vsgb", options);

How to use vsgconv utility that is built as part of vsgXchange

To convert shaders to SPIRV, native VSG format or source file:

vsgconv myshader.vert myshader.vsgb
vsgconv myshader.frag myshader.spv
vsgconv myshader.comp myshader_comp.cpp

To convert 3rd party image formats to native VSG format or source file:

vsgconv image.jpg image.vsgb
vsgconv image.jpg image.cpp

To convert 3rd party model formats to native VSG format or source file:

vsgconv mymodel.obj mymodel.vsgt # convert OBJ model to VSG ascii text format (requires Assimp)
vsgconv mymodel.gltif mymodel.vsgt # convert GLTF model to VSG ascii text format  (requires Assimp)
vsgconv mymodel.osgb mymodel.vsgb # convert OSG binary format to VSG binary format (requires osg2vsg/OpenSceneGraph)
vsgconv mymodel.flt mymodel.vsgb # convert OpenFlight format to VSG binary format (requires osg2vsg/OpenSceneGraph)
vsgconv mymodel.vsgb mymodel.cpp # convert native VSG binary format to source file.

To convert an OpenSceneGraph Paged database (requires osg2vsg/OpenSceneGraph):

vsgconv OsgDatabase/earth.osgb VsgDatabase/earth.vsgb -l 30 # convert up to level 30

Options specific to a ReaderWriter are specified on the commandline using two dashes:

vsgconv FlightHelmet.gltf helmet.vsgb --discard_empty_nodes false

File formats supported by all built in ReaderWriters

vsgXchange::all
    vsgXchange::curl provides support for 0 extensions, and 2 protocols.
        Protocols       Supported ReaderWriter methods
        ----------      ------------------------------
        http            read(vsg::Path, ..)
        https           read(vsg::Path, ..)

        vsg::Options::Value  type
        -------------------  ----
        CURLOPT_SSL_OPTIONS  uint32_t

    vsg::VSG provides support for 2 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .vsgb           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..) write(vsg::Path, ..) write(std::ostream, ..)
        .vsgt           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..) write(vsg::Path, ..) write(std::ostream, ..)

    vsg::spirv provides support for 1 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .spv            read(vsg::Path, ..) write(vsg::Path, ..)

    vsg::glsl provides support for 16 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .comp           read(vsg::Path, ..) write(vsg::Path, ..)
        .frag           read(vsg::Path, ..) write(vsg::Path, ..)
        .geom           read(vsg::Path, ..) write(vsg::Path, ..)
        .glsl           read(vsg::Path, ..) write(vsg::Path, ..)
        .hlsl           read(vsg::Path, ..) write(vsg::Path, ..)
        .mesh           read(vsg::Path, ..) write(vsg::Path, ..)
        .rahit          read(vsg::Path, ..) write(vsg::Path, ..)
        .rcall          read(vsg::Path, ..) write(vsg::Path, ..)
        .rchit          read(vsg::Path, ..) write(vsg::Path, ..)
        .rgen           read(vsg::Path, ..) write(vsg::Path, ..)
        .rint           read(vsg::Path, ..) write(vsg::Path, ..)
        .rmiss          read(vsg::Path, ..) write(vsg::Path, ..)
        .task           read(vsg::Path, ..) write(vsg::Path, ..)
        .tesc           read(vsg::Path, ..) write(vsg::Path, ..)
        .tese           read(vsg::Path, ..) write(vsg::Path, ..)
        .vert           read(vsg::Path, ..) write(vsg::Path, ..)

    vsgXchange::bin provides support for 1 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .bin            read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)

    vsgXchange::gltf provides support for 2 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .glb            read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)
        .gltf           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)

        vsg::Options::Value  type
        -------------------  ----
        clone_accessors      bool
        culling              bool
        disable_gltf         bool
        maxAnisotropy        float
        report               bool

    vsgXchange::Tiles3D provides support for 6 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .b3dm           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)
        .cmpt           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)
        .i3dm           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)
        .json           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)
        .pnts           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)
        .tiles          read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)

        vsg::Options::Value  type
        -------------------  ----
        instancing           bool
        pixel_ratio          double
        pre_load_level       uint
        report               bool

    vsg::json provides support for 1 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .json           read(vsg::Path, ..) read(std::istream, ..) read(uint8_t* ptr, size_t size, ..)

    vsgXchange::cpp provides support for 1 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .cpp            write(vsg::Path, ..)

    vsg::txt provides support for 7 extensions, and 0 protocols.
        Extensions      Supported ReaderWriter methods
        ----------      ------------------------------
        .bat            read(vsg::Path, ..) read(s