Telescope (v0.2.0)

An Open-Source Toolkit for Interactive Multimedia Applications

---

Table of Contents

1. Dependencies
   1.1. Bullet
   1.2. Vulkan
   1.3. SDL2
   1.4. glm
   1.5. shaderc
   
2. Installation
   
3. Troubleshooting
   
4. License
   
5. Authors

---

Dependencies

To build Telescope from source, the following dependencies need to be met:

• Bullet
  • also available as libbullet-dev
• Vulkan via LunarG
  • also available as libvulkan-dev recommended for non Ubuntu development.
  • Or as the vulkan-sdk on e.g. Ubuntu 20.04

    wget -qO - http://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo apt-key add -
    sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-focal.list http://packages.lunarg.com/vulkan/lunarg-vulkan-focal.list
    sudo apt update
    sudo apt install vulkan-sdk
    

• SDL2
  • also available as libsdl2-dev
  • additionally, libsdl2-image-dev, libsdl2-mixer-dev, libsdl2-ttf-dev, libsdl2-net-dev may need to be installed separately
• glm
  • also available as libglm-dev
• shaderc
  • also available as shaderc if the vulkan-sdk is installed
    • dpkg -L shaderc | grep libshaderc_shared.so should then show the path to supply to -DSHADERC_LIB_DIR=/path/to/shaderc/lib discussed in the shaderc_shared section below.

Clicking on the links above will lead you to the correct download pages for each dependency. Alternatively, they can be installed through your package manager, potentially under the names supplied above.

---

Installation

To install Telescope, execute, in any public directory:

git clone https://github.com/jhigginbotham64/Telescope
cd Telescope
git submodule update --init --recursive
mkdir build
cd build
cmake .. #-DCMAKE_INSTALL_PREFIX=<install location>
make clean
make install # may require sudo depending <install location>

Where -DCMAKE_INSTALL_PREFIX=<install location> is an optional argument that determines, what directory the Telescope shared library will be installed into.

After installation, you can interface with Telescope from Julia using Starlight.jl.

If you wish to use telescope for your C / C++ application, in your own CMakeLists.txt, add the following lines:

find_library(telescope REQUIRED 
    NAMES telescope
    #PATHS <install location>
)
target_link_libraries(<your_target> PRIVATE telescope)

Where

• <your_target> is the name of your CMake library or executable
• <install location> is the location specified during CMake configuration earlier

Then, you can make Telescope available to your library using

#include <telescope.h>

---

Unit Tests

After following the steps in Installation, you can run Telescope's unit tests from your build directory using

make test

---

Troubleshooting

telescope.h: No such file or directory

When compiling your own C / C++ target that uses telescope, the following compiler error may occur:

/home/.../main.cpp: fatal error: telescope.h: No such file or directory
   11 | #include <telescope.h>
      |          ^~~~~~~~~~~~~

This happens if the telescope install directory was not added to your CMake targets include directories. To address this, in your own CMakeLists.txt, add the following lines:

find_library(telescope REQUIRED 
    NAMES telescope
    PATHS <install location>
)
target_include_directories(<your_target> PRIVATE <install location>)
target_link_libraries(<your_target> PRIVATE telescope)

Where

• <your_target> is the name of your CMake executable or library
• <install loaction> is the directory specified as CMAKE_INSTALL_PREFIX during CMake configuration

Now, your compiler should be able to locate telescope.h properly.

Could not find shaderc_shared

During CMake configuration, the following error may occur:

Unable to detect shaderc_shared library.  Make sure it is installed
correctly.  You can manually specify the path using:

   -DSHADERC_LIB_DIR=/path/to/shaderc/lib

 during cmake configuration.

CMake Error at cmake/Findshaderc_shared.cmake:30 (find_library):
  Could not find shaderc_shared using the following names:
  libshaderc_shared.so

This means Telescope was unable to detect the shaderc_shared library, which is part of the shaderc package. If you are sure shaderc is already installed properly, you can manually specify the path to the shared library using the SHADERC_LIB_DIR CMake variable during configuration, like so:

# in Telescope/build
cmake .. -DSHADERC_LIB_DIR=/path/to/shaderc/lib

Where /path/to/shaderc/lib should point to a directory that has the following layout:

shaderc/
  bin/
  include/ 
  lib/
    libshaderc_shared.so
    (...)
  share/ 

Where libshaderc_shared.so may have a different prefix and/or suffix depending on your system, for example shaderc_shared.dll.

---

License

The current and all previous versions of Telescope are supplied under MIT License, available here.

---

Authors

Telescope was created and implemented by Joshua Higginbotham.

May 2022

• Documentation, CMake Improvements by Clemapfel