UnrealXR/raylib-python-cffi
Archived
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix docs

Browse source
This commit is contained in:
richard 2021-10-08 05:23:06 +01:00
parent e04d61f60b
commit 80d568a469
53 changed files with 34290 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

245
docs/_sources/BUILDING.rst.txt Normal file
View file

@ -0,0 +1,245 @@
Building from source
====================
Have Pip build from source
--------------------------
Useful if the binaries don’t work on your system.
Make sure Raylib is installed and then:
::
pip3 install --no-binary raylib --upgrade --force-reinstall raylib
Build from source manually
--------------------------
Useful if the Pip build doesn’t work and you want to debug it, or you want to contribute to the
project.
.. attention::
If the Pip build doesn’t work, please submit a bug. (And if you have
fixed it, a PR.)
Manual instructions follow, but see also how we actually build the wheels
at https://github.com/electronstudio/raylib-python-cffi/blob/master/.github/workflows/build.yml
Windows manual build
~~~~~~~~~~~~~~~~~~~~
Clone this repo including submodules so you get correct version of
Raylib.
::
git clone --recurse-submodules https://github.com/electronstudio/raylib-python-cffi
Open Visual C++ command shell.
Fix the symlink that doesnt work on Windows
::
cd raylib-python-cffi
copy raylib-c\src\raylib.h raylib\raylib.h
Build and install Raylib from the raylib-c directory.
::
cd raylib-python-cffi/raylib-c
mkdir build
cd build
cmake -DWITH_PIC=on -DCMAKE_BUILD_TYPE=Release ..
msbuild raylib.sln /target:raylib /property:Configuration=Release
copy raylib\Release\raylib.lib ..\..
cd ..\..
To update the dynamic libs, download the official release,
e.g. https://github.com/raysan5/raylib/releases/download/3.7.0/raylib-3.7.0_win64_msvc16.zip
and extract ``raylib.dll`` into ``dynamic/raylib``.
To build a binary wheel distribution:
::
rmdir /Q /S build
pip3 install cffi
pip3 install wheel
python setup.py bdist_wheel
Alternatively, if you don’t want the static binaries and just want to
use DLLs with raylib.dynamic:
::
python3 setup_dynamic.py bdist_wheel
Then install it:
::
pip3 install dist\raylib-3.7.0-cp37-cp37m-win_amd64.whl
(Note: your wheel’s filename will probably be different than the one
here.)
Linux manual build
~~~~~~~~~~~~~~~~~~~~~~
These instructions have been tested on Ubuntu 20.10 and 16.04.
Clone this repo including submodules so you get correct version of
Raylib.
::
git clone --recurse-submodules https://github.com/electronstudio/raylib-python-cffi
Build and install Raylib from the raylib-c directory.
::
sudo apt install cmake libasound2-dev mesa-common-dev libx11-dev libxrandr-dev libxi-dev xorg-dev libgl1-mesa-dev libglu1-mesa-dev
cd raylib-python-cffi/raylib-c
mkdir build
cd build
cmake -DWITH_PIC=on -DCMAKE_BUILD_TYPE=Release ..
sudo make install
.. note:: Optional: Build the Raylib shared libs, if you plan to use
``raylib_dynamic`` binding.
::
rm -rf *
cmake -DWITH_PIC=on -DBUILD_SHARED_LIBS=on -DCMAKE_BUILD_TYPE=Release ..
make
sudo make install
::
cd ../..
.. note:: Optional: Make a patched version of raylib header. (**Not necessary** if
you’ve already got raylib_modifed.h from repo and haven’t changed
anything.)
::
cd raylib
cp raylib.h raylib_modified.h
patch -p0 <raylib_modified.h.patch
cd ..
Build
::
pip3 install cffi
rm -rf build raylib/_raylib_cffi.*
python3 raylib/build.py
.. note:: (Optional) To update the Linux dynamic libs (names will be different on other platfroms):
::
rm dynamic/raylib/*.so*
cp -P /usr/local/lib/libraylib.so* dynamic/raylib/
To build a binary wheel distribution:
::
pip3 install wheel
python3 setup.py bdist_wheel
Then install it:
::
pip3 install dist/raylib*.whl
To build a complete set of libs for Python 3.6, 3.7, 3.8 and 3.9:
::
./raylib/build_multi.sh
.. warning::
pypi wont accept Linux packages unless they are built
``--plat-name manylinux2014_x86_64`` so on linux please run
``./raylib/build_multi_linux.sh`` )
.. TODO::
Separate the instructions for preparing the dynamic module
from the instructions for building the static module!
Macos manual build
~~~~~~~~~~~~~~~~~~~~~~
These instructions have been tested on Macos 10.14.
Clone this repo including submodules so you get correct version of
Raylib.
::
git clone --recurse-submodules https://github.com/electronstudio/raylib-python-cffi
Build and install Raylib from the raylib-c directory.
::
cd raylib-python-cffi/raylib-c/src
make
sudo cp libraylib.a /usr/local/lib/libraylib.a
cd ../..
Build and install module.
::
pip3 install cffi
rm -rf build raylib/_raylib_cffi.*
python3 raylib/build.py
pip3 install wheel
python3 setup.py install
Raspberry Pi
~~~~~~~~~~~~
The integrated GPU hardware in a Raspberry Pi (“VideoCore”) is rather
idiosyncratic, resulting in a complex set of software options. Probably
the most interesting two options for Raylib applications are:
1. Use the Broadcom proprietary Open GL ES 2.0 drivers, installed by
Raspbian into ``/opt/vc``. These are 32-bit only, and currently X11
doesn’t use these for its acceleration, so this is most suitable for
driving the entire HDMI output from one application with minimal
overhead (no X11).
2. Use the more recent open-source ``vc4-fkms-v3d`` kernel driver. This
can run in either 32-bit or 64-bit, and X11 can use these, so using
X11 is probably the more common choice here.
With option 2, the regular linux install instructions above should
probably work as-is.
For option 1, then also follow the above instructions, but with these
modifications:
- With ``cmake``, use
``cmake -DWITH_PIC=on -DSTATIC=on -DSHARED=on -DPLATFORM='Raspberry Pi' ..``
(See
`here <https://github.com/electronstudio/raylib-python-cffi/issues/31#issuecomment-862078330>`__
for a Raspberry Pi wheel)

112
docs/_sources/README.md.txt Normal file
View file

@ -0,0 +1,112 @@
# Python Bindings for Raylib 3.7
New CFFI API static bindings. Automatically generated to be as close as possible to
original Raylib. Faster, fewer bugs and easier to maintain than ctypes. Commercial-friendly license.
Docstrings and auto-completion.
[Full documentation](http://electronstudio.github.io/raylib-python-cffi)
# Quickstart
`pip3 install raylib`
from pyray import *
init_window(800, 450, "Hello")
while not window_should_close():
begin_drawing()
clear_background(WHITE)
draw_text("Hello world", 190, 200, 20, VIOLET)
end_drawing()
close_window()
# Installation
First make sure you have latest pip installed:
python3 -m pip install --upgrade pip
Then install
python3 -m pip install raylib
On most platforms it should install a binary wheel (Windows 10 x64, MacOS 10.15 x64, Linux Ubuntu1804 x64).
If yours isn't available then pip will attempt to build from source, in which case you will need to have Raylib development libs installed, e.g.
using homebrew, apt, etc.
[If it doesn't work, you can build manually.](BUILDING.md)
## Dynamic binding version
There is now a separate dynamic version of this binding:
python3 -m pip install raylib_dynamic
[Read this before using raylib_dynamic](https://electronstudio.github.io/raylib-python-cffi/dynamic.html)
# How to use
There are two APIs, you can use either or both:
### If you are familiar with C coding and the Raylib C library and you want to use an exact copy of the C API
Use [the C API](https://electronstudio.github.io/raylib-python-cffi/raylib.html).
### If you prefer a slightly more Pythonistic API and don't mind it might be slightly slower
Use [the Python API](https://electronstudio.github.io/raylib-python-cffi/pyray.html).
# RLZero
A related library (that is a work in progress!):
[A simplified API for Raylib for use in education and to enable beginners to create 3d games](https://github.com/electronstudio/rlzero)
# Help wanted
* Converting more examples from C to Python
* Testing on more platforms
# License (updated)
The bindings are now under the Eclipse Public License, so you are free to
statically link and use in non-free / proprietary / commercial projects!
# Performance
For fastest performance use Pypy rather than standard Python.
Every call to C is costly, so it's slightly faster if you use Python data structures and functions when calculating
in your update loop
and then only convert them to C data structures when you have to call the C functions for drawing.
## Bunnymark
| Library | Implementation | Bunnies (60 FPS) | Percentage |
| ------------- | ------------- | ------------- | ------------- |
| Raylib 3.7 | C | 168100 | 100% |
| Raylib Python CFFI 3.7 | Pypy 3.7 | 33800 | 20% |
| Raylib Python CFFI 3.7 | Python 3.9 | 7700 | 4.5% |
| Raylib Python CFFI 3.7 | Python 3.9 Nuitka | 8600 | 5.1% |
| Raylib Python CFFI 3.7 Dynamic | Python 3.9 | 6300 | 3.7% |
# Packaging your app
You can create a standalone binary using the Nuitka compiler. For example, here is how to package Bunnymark:
pip3 install nuitka
cd examples/textures
python3 -m nuitka --onefile --linux-onefile-icon resources/wabbit_alpha.png textures_bunnymark.py
# Advert
[RetroWar: 8-bit Party Battle](https://store.steampowered.com/app/664240/RetroWar_8bit_Party_Battle/?git) is out now. Defeat up to 15 of your friends in a tournament of 80s-inspired retro mini games.
[Coding Games With Pygame Zero & Python](https://github.com/electronstudio/pygame-zero-book) is
a book for Python beginners.

38
docs/_sources/dynamic.rst.txt Normal file
View file

@ -0,0 +1,38 @@
Dynamic Bindings
================
CFFI ABI dynamic bindings avoid the need to compile a C extension module. They now been moved to a separate module::
python3 -m pip install raylib_dynamic
.. warning::
There have been some weird failures with dynamic bindings and ctypes bindings before and often the
failures are silent
so you don't even know something has gone wrong and you don't get proper stacktraces. Also the static bindings are faster.
Therefore I personally recommend the static ones.
But the dynamic bindings have the advantage that you don't need to compile anything to install. You just need a Raylib DLL.
API is exactly the same as the static one documented here. (Therefore you can't have both modules installed at once.) The only difference is you can't do::
from raylib import *
Instead you have to do::
from raylib import rl
Then you access the functions with ``rl.`` prefix.
See https://github.com/electronstudio/raylib-python-cffi/blob/master/dynamic/test_dynamic.py for an example.
If you use the ``rl.`` prefix then code will work on both static and dynamic bindings.
.. tip::
If you access functions via ``import pyray`` then there is no difference at all, but be warned this hasn't been tested much.
.. important::
If your system already has the Raylib library installed, you can set the environment variable ``USE_EXTERNAL_RAYLIB`` and it will
always be used instead of the bundled DLLs.

24
docs/_sources/index.rst.txt Normal file
View file

@ -0,0 +1,24 @@
.. RL Zero documentation master file, created by
sphinx-quickstart on Mon Jul 12 14:03:57 2021.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Raylib Python
===================================
.. toctree::
:maxdepth: 1
:caption: Contents:
README
pyray
raylib
dynamic
BUILDING
* :ref:`search`

66
docs/_sources/pyray.rst.txt Normal file
View file

@ -0,0 +1,66 @@
Python API
==============
.. comment::
Link to API reference:
toctree::
:maxdepth: 1
autoapi/pyray/index
This is a wrapper around the C API with some syntactic sugar.
The API is *still the same as Raylib*, so you should still reply on `the official Raylib docs <https://www.raylib.com/cheatsheet/cheatsheet.html>`_, except:
* the function names are in **snake_case**.
* Some string and pointer conversions are handled automatically.
* There are some helper functions to create structures.
Example program:
.. code-block::
import pyray as pr
pr.init_window(800, 450, "Hello Pyray")
pr.set_target_fps(60)
camera = pr.Camera3D([18.0, 16.0, 18.0], [0.0, 0.0, 0.0], [0.0, 1.0, 0.0], 45.0, 0)
pr.set_camera_mode(camera, pr.CAMERA_ORBITAL)
while not pr.window_should_close():
pr.update_camera(camera)
pr.begin_drawing()
pr.clear_background(pr.RAYWHITE)
pr.begin_mode_3d(camera)
pr.draw_grid(20, 1.0)
pr.end_mode_3d()
pr.draw_text("Hello world", 190, 200, 20, pr.VIOLET)
pr.end_drawing()
pr.close_window()
.. tip:: New in 3.7.0.post9:
You can also now import the functions with no prefix:
.. code-block::
from pyray import *
init_window(800, 450, "Raylib texture test")
...
You don't need to use the PyRay() class anymore.
See also https://github.com/electronstudio/raylib-python-cffi/blob/master/tests/test_pyray.py
API reference
-------------
.. autoapimodule:: pyray
:members:
:undoc-members:

58
docs/_sources/raylib.rst.txt Normal file
View file

@ -0,0 +1,58 @@
C API
=============
The goal of the C API is make usage as similar to the original C as CFFI will allow. The `example programs <https://github.com/electronstudio/raylib-python-cffi/tree/master/examples>`_
are very, very similar to the C originals.
Example program:
.. code-block::
from raylib import *
InitWindow(800, 450, b"Hello Raylib")
SetTargetFPS(60)
camera = ffi.new("struct Camera3D *", [[18.0, 16.0, 18.0], [0.0, 0.0, 0.0], [0.0, 1.0, 0.0], 45.0, 0])
SetCameraMode(camera[0], CAMERA_ORBITAL)
while not WindowShouldClose():
UpdateCamera(camera)
BeginDrawing()
ClearBackground(RAYWHITE)
BeginMode3D(camera[0])
DrawGrid(20, 1.0)
EndMode3D()
DrawText(b"Hellow World", 190, 200, 20, VIOLET)
EndDrawing()
CloseWindow()
If you want to be more portable (i.e. same code will work with dynamic bindings) you can prefix the functions like this:
.. code-block::
from raylib import ffi, rl, colors
rl.InitWindow(800, 450, b"Hello Raylib")
rl.SetTargetFPS(60)
...
See also https://github.com/electronstudio/raylib-python-cffi/blob/master/tests/test_static.py
.. note:: Whenever you need to convert stuff between C and Python see https://cffi.readthedocs.io
.. important:: Your **primary reference** should always be `the official Raylib docs <https://www.raylib.com/cheatsheet/cheatsheet.html>`_
However, here is a list of available functions:
Functions API reference
-----------------------
.. autoapimodule:: raylib
:members:
:undoc-members: