Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/gasman/shortcrust

A Python OpenGL framework for Raspberry Pi and the demoscene
https://github.com/gasman/shortcrust

Last synced: 2 months ago
JSON representation

A Python OpenGL framework for Raspberry Pi and the demoscene

Awesome Lists containing this project

README 

        
* Shortcrust *



Shortcrust is a Python wrapper library for OpenGL, intended for building

applications that are portable to the Raspberry Pi.



On machines where PyOpenGL is available (hereafter referred to as

'grown-up machines'), the standard PyOpenGL API methods will be accessible

to the application, with GLUT used to handle housekeeping tasks such as opening

viewport windows. When running on Raspberry Pi, the binary OpenGL ES driver is

wrapped to provide a subset of the PyOpenGL API. PyGame (shipped with the

default Raspbian install) is used for additional functions such as texture

loading.



The primary motivation for Shortcrust is creating demoscene productions

 - however, it is hoped that it will

find wider use for 3D applications in general.



** BaseGLApp **



Applications in Shortcrust are implemented as subclasses of

shortcrust.BaseGLApp. Generally you will override the following methods:



* setup(self) - called once after the GL viewport has been created

* draw(self, time) - called repeatedly to render video frames. 'time' is the

  number of seconds since the application was started.

* on_exit(self) - called immediately before exiting the application. On

  grown-up machines, pressing escape causes an exit; you can also initiate one

  within your application by calling self.exit().



You can also set the following properties on your BaseGLApp subclass to

customise behaviour:



* fullscreen (default=False): If true, the application opens in a full-screen

  viewport on grown-up machines. On Raspberry Pi, applications are always

  full-screen.

* title: Specifies the title text for the viewport window on grown-up machines.

  No effect on Raspberry Pi (or when fullscreen=True).

* depthbuffer (default=True): Creates a GL viewport with depth buffer support

  enabled (pretty much essential for rendering any kind of 3D scenes).



Additionally, the properties 'width', 'height' and 'aspect_ratio' are defined,

to give information about the viewport dimensions.



** GL functions **



The following functions are available within the shortcrust.gl2 module,

following the PyOpenGL API

:



glActiveTexture

glAttachShader

glBindAttribLocation

glBindBuffer

glBindFramebuffer

glBindTexture

glBlendFunc

glBlendFuncSeparate

glBufferData

glClear

glClearColor

glCompileShader

glCreateProgram

glCreateShader

glCullFace

glDepthRangef

glDrawArrays

glDrawElements

glEnable

glEnableVertexAttribArray

glFinish

glFrontFace

glGenBuffers (does not currently support returning more than 1 buffer)

glGenTextures (does not currently support returning more than 1 texture)

glGetProgramInfoLog

glGetShaderInfoLog

glGetShaderiv

glGetString

glGetUniformLocation

glLinkProgram

glPixelStorei

glShaderSource

glTexImage2D

glTexParameteri

glUniform1f

glUniform2f

glUniform3f

glUniform4f

glUniform1i

glUniform2i

glUniform3i

glUniform4i

glUniform1fv

glUniform2fv

glUniform3fv

glUniform4fv

glUniform1iv

glUniform2iv

glUniform3iv

glUniform4iv

glUniformMatrix2fv

glUniformMatrix3fv

glUniformMatrix4fv

glUseProgram

glValidateProgram

glVertexAttribPointer

glViewport



As with PyOpenGL, error checking takes place after every GL operation, and

any errors are thrown as exceptions (of type GLError).



** Other batteries included **



* shortcrust.matrix is a library for performing matrix / vector operations,

  ported from gl-matrix by Brandon Jones: https://github.com/toji/gl-matrix

  The data structures it works with (as created by mat3.create(), mat4.create()

  and vec3.create()) are arrays of type GLfloat, suitable for passing as

  parameters to GL functions such as glUniformMatrix4fv.

* shortcrust.shader provides ShaderProgram, an abstract class that encapsulates

  a vertex shader / fragment shader pair, taking care of the details of

  compiling and linking them. It's intended that you should query the attribute

  and uniform locations within your shader using the provided get_attrib and

  get_uniform methods, and expose them as methods of your ShaderProgram object.

* shortcrust.buffer provides wrappers for various types of buffer, allowing you

  to push data in the form of arrays onto the graphics card.

* shortcrust.texture handles the uploading of texture data into GPU memory,

  using any image file format supported by PyGame as a starting point.

* shortcrust.geometry provides a number of primitive shape classes which can be

  combined and converted to a polygon mesh for rendering with a shader.



  Take a look at the example projects to see how it all fits together.

  When running the examples, you'll need to ensure that the shortcrust library

  is within your PYTHONPATH - one way of doing this is:

    cd examples

    PYTHONPATH=$PYTHONPATH:.. ./plasma.py



** Acknowledgements **



* Ben O'Steen - for the documentation and example code for framebuffer-based

  access to OpenGL ES on the RasPi:

  http://benosteen.wordpress.com/2012/04/27/using-opengl-es-2-0-on-the-raspberry-pi-without-x-windows/

* Peter de Rivaz - for the initial work on Python EGL / OpenGL ES bindings for

  the RasPi, which served as the starting point for this project:

  https://github.com/peterderivaz/pyopengles

* Sir Garbagetruck - for pointing me at the above and planting the idea of

  using Python for RasPi demos

* Giles Thomas - for the WebGL tutorials that steered me in the right direction

  with OpenGL ES and indirectly informed the API design

* Brandon Jones - for the glMatrix Javascript library, various sections of

  which I've ported to Python with minimal changes:

  https://github.com/toji/gl-matrix

* mnstrmnch - for troubleshooting thorny problems with alpha channels



** Author **



Matt Westcott  - [email protected]

twitter.com/gasmanic