| Installation Guide |
| ================== |
|
|
| Python Installation |
| ------------------- |
|
|
| This package is available via ``pip``. |
|
|
| .. code-block:: bash |
|
|
| pip install pyrender |
|
|
| If you're on MacOS, you'll need |
| to pre-install my fork of ``pyglet``, as the version on PyPI hasn't yet included |
| my change that enables OpenGL contexts on MacOS. |
|
|
| .. code-block:: bash |
|
|
| git clone https://github.com/mmatl/pyglet.git |
| cd pyglet |
| pip install . |
|
|
| .. _osmesa: |
|
|
| Getting Pyrender Working with OSMesa |
| ------------------------------------ |
| If you want to render scenes offscreen but don't want to have to |
| install a display manager or deal with the pains of trying to get |
| OpenGL to work over SSH, you have two options. |
|
|
| The first (and preferred) option is using EGL, which enables you to perform |
| GPU-accelerated rendering on headless servers. |
| However, you'll need EGL 1.5 to get modern OpenGL contexts. |
| This comes packaged with NVIDIA's current drivers, but if you are having issues |
| getting EGL to work with your hardware, you can try using OSMesa, |
| a software-based offscreen renderer that is included with any Mesa |
| install. |
|
|
| If you want to use OSMesa with pyrender, you'll have to perform two additional |
| installation steps: |
|
|
| - :ref:`installmesa` |
| - :ref:`installpyopengl` |
|
|
| Then, read the offscreen rendering tutorial. See :ref:`offscreen_guide`. |
|
|
| .. _installmesa: |
|
|
| Installing OSMesa |
| ***************** |
|
|
| As a first step, you'll need to rebuild and re-install Mesa with support |
| for fast offscreen rendering and OpenGL 3+ contexts. |
| I'd recommend installing from source, but you can also try my ``.deb`` |
| for Ubuntu 16.04 and up. |
|
|
| Installing from a Debian Package |
| ******************************** |
|
|
| If you're running Ubuntu 16.04 or newer, you should be able to install the |
| required version of Mesa from my ``.deb`` file. |
|
|
| .. code-block:: bash |
|
|
| sudo apt update |
| sudo wget https://github.com/mmatl/travis_debs/raw/master/xenial/mesa_18.3.3-0.deb |
| sudo dpkg -i ./mesa_18.3.3-0.deb || true |
| sudo apt install -f |
|
|
| If this doesn't work, try building from source. |
|
|
| Building From Source |
| ******************** |
|
|
| First, install build dependencies via `apt` or your system's package manager. |
|
|
| .. code-block:: bash |
|
|
| sudo apt-get install llvm-6.0 freeglut3 freeglut3-dev |
|
|
| Then, download the current release of Mesa from here_. |
| Unpack the source and go to the source folder: |
|
|
| .. _here: https://archive.mesa3d.org/mesa-18.3.3.tar.gz |
|
|
| .. code-block:: bash |
|
|
| tar xfv mesa-18.3.3.tar.gz |
| cd mesa-18.3.3 |
|
|
| Replace ``PREFIX`` with the path you want to install Mesa at. |
| If you're not worried about overwriting your default Mesa install, |
| a good place is at ``/usr/local``. |
|
|
| Now, configure the installation by running the following command: |
|
|
| .. code-block:: bash |
|
|
| ./configure --prefix=PREFIX \ |
| --enable-opengl --disable-gles1 --disable-gles2 \ |
| --disable-va --disable-xvmc --disable-vdpau \ |
| --enable-shared-glapi \ |
| --disable-texture-float \ |
| --enable-gallium-llvm --enable-llvm-shared-libs \ |
| --with-gallium-drivers=swrast,swr \ |
| --disable-dri --with-dri-drivers= \ |
| --disable-egl --with-egl-platforms= --disable-gbm \ |
| --disable-glx \ |
| --disable-osmesa --enable-gallium-osmesa \ |
| ac_cv_path_LLVM_CONFIG=llvm-config-6.0 |
|
|
| Finally, build and install Mesa. |
|
|
| .. code-block:: bash |
|
|
| make -j8 |
| make install |
|
|
| Finally, if you didn't install Mesa in the system path, |
| add the following lines to your ``~/.bashrc`` file after |
| changing ``MESA_HOME`` to your mesa installation path (i.e. what you used as |
| ``PREFIX`` during the configure command). |
|
|
| .. code-block:: bash |
|
|
| MESA_HOME=/path/to/your/mesa/installation |
| export LIBRARY_PATH=$LIBRARY_PATH:$MESA_HOME/lib |
| export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MESA_HOME/lib |
| export C_INCLUDE_PATH=$C_INCLUDE_PATH:$MESA_HOME/include/ |
| export CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:$MESA_HOME/include/ |
|
|
| .. _installpyopengl: |
|
|
| Installing a Compatible Fork of PyOpenGL |
| **************************************** |
|
|
| Next, install and use my fork of ``PyOpenGL``. |
| This fork enables getting modern OpenGL contexts with OSMesa. |
| My patch has been included in ``PyOpenGL``, but it has not yet been released |
| on PyPI. |
|
|
| .. code-block:: bash |
|
|
| git clone https://github.com/mmatl/pyopengl.git |
| pip install ./pyopengl |
|
|
|
|
| Building Documentation |
| ---------------------- |
|
|
| The online documentation for ``pyrender`` is automatically built by Read The Docs. |
| Building ``pyrender``'s documentation locally requires a few extra dependencies -- |
| specifically, `sphinx`_ and a few plugins. |
|
|
| .. _sphinx: http://www.sphinx-doc.org/en/master/ |
|
|
| To install the dependencies required, simply change directories into the `pyrender` source and run |
|
|
| .. code-block:: bash |
|
|
| $ pip install .[docs] |
|
|
| Then, go to the ``docs`` directory and run ``make`` with the appropriate target. |
| For example, |
|
|
| .. code-block:: bash |
|
|
| $ cd docs/ |
| $ make html |
|
|
| will generate a set of web pages. Any documentation files |
| generated in this manner can be found in ``docs/build``. |
|
|
