pyrender/docs/source/install/index.rst

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``.