20.09.2010

3D PyEngine for S60:

This small engine is written in python and uses only standart python modules (no need to install any additional modules). OpenGL is used to display 3D objects. All devices with more than ~30 mb free Ram should not have any problems to run simple graphics (over 5 textures with 512x512 pixel and over a few thousand triangles). For advanced 3D graphics devices wthout hardware acceleration will react with slowness. It works with almost any python version. Tested versions:

• 1.4.5 works perfectly
• 1.9.6 works
• 1.9.7 works perfectly
• 2.0.0 works, but needs more ram

Current version v0.04 consists of 2 Libs:

• e_imp.py is a simple module that imports and updates the main engine
• e_core.py is the main module of the engine and is imported by the e_imp.py module

This Engine has a few nice features:

• fps var is customizable (to lock the max FPS)
• frustum settings are customizable (camera lens behavior)
• fog (not working with some devices)
• camera's position and angle can be changed
• import of 3D objects with texture and masks for transparency (*.obj + *.mtl files and their textures in any image format supported)
• position, angle, scale of mesh can be changed, textures can be scaled and moved
• console can be turned off and on to display importand values
• keyboard class exsists to recognice keypress
• touch events should be possible (not tested, because of missing 5th ed device)
• BT connection for possible multiplayer games
• a WLAN connection between PC and phone as console
• and much more...

Installation is quite simple. Just install python on your device and create a new folder called Lib in e:\Python\ (e:\ means card-slot). Copy both files (e_imp.py and e_core.py) into e:\Python\Lib\ and you are done.

If you want to use it just import e_imp.py in your script (from e_imp import *) and use it as any other python module. For aditional help just take a look at the tutorials.

All user relevant vars/functions/classes explained:

Vars:


modules stores the count of imported modules.
total_modules stores the total count of modules that should get imported.
Both values are good to check if the engine started right.

py_version contains the Python version in a list.
Useful to check under which Python runtime the script is running.

topw is 1 if TopWindow got imported, is 2 if topwindow got imported, is 0 if import failed.
The value depends on the python version (1.4.x or smaller / 1.9.x or greater).

sen is 1 if sensor got imported, 0 if import failed.
Check if the phone has an accelerometer sensor.

sensor_on is 1 if sensor got imported and started, 0 if start failed.
Check if the accelerometer sensor runs.(This var is also in the console)

touch_on is 1 if the device has a touchscreen, 0 if no touchscreen found.
Useful to check if the phone has a touch screen. (This var will be soon in the console)

keyboard_on is 1 if keypress are recognized, 0 if not.
Check if the phone's keyboard can be used.(This var is also in the console)

objects stores the count of loaded models.
(This var is also in the console)

connection BT connection status, connected as: 1(server),2(client),0(no connection)
Useful for connection dependent script

console_redraw_time (default value is 10) after 10 frames the console gets updated
Can be changed to any value (integer) greater than 0.

running 1 if engine runs, 0 if right softkey got pressed.
Useful to check if the engine got shutdown by the user.

Functions:


set_screen(mode,arg1,arg2,arg3,arg4,arg5,arg6) has 2 modes:


'glClearColorx' changes the background color, arguments are:
• arg1: Red value from 0 - arg4 (default = 0)
• arg2: Green value from 0 - arg4 (default = 0)
• arg3: Blue value from 0 - arg4 (default = 0)
• arg4: Max value

'glFrustumf' changes Frustum values, arguments are:
• arg1: left, sets the left screen border (default = -1.0)
• arg2: right, sets the right screen border (default = 1.0)
• arg3: bottom, sets the bottom screen border (default = -1.0)
• arg4: top, sets the top screen border (default = 1.0)
• arg5: near, sets viewrange (from near to far) (default = 3.0)
• arg6: far, sets viewrange (from near to far) (default = 1000.0)
If arguments are missing last ones are used.

cleanupsensor() shutsdown the accelerometer sensor
This function function is finaly integerated into the SensorConnection Class and is not longer available since e_core version 0.04.

start_bt_server( service_name) starts a BT server side connection.
Var connection is now 1.
Same service_name should be used in con_bt_client( service_name).

con_bt_client( service_name) connect to the BT server.
Var connection is now 2.
Same service_name should be used in start_bt_server( service_name).

bt_send_cmd(code) sends python code to the server/client
All devices should be connected already and code should be a unicode string containing python code.

bt_receive_cmd() If there is incoming code from bt_send_cmd( code) it gets executed.
Should be called in a loop eg. mainloop of the script.
May have bugs.

wlan_connect() starts a wlan server, the accespoint you can select should be your wlan router or an ad-hoc accesspoint.
The script is blocked till a computer is connected. Your computer should connect to your phones IP.

receive_cmd() should be called olny if a command comes from the computer, otherwise the script is blocked till a command comes.
A connection must exist! I used a key to trigger this function after i sent a command.

close_connection() close the exsisting wlan connection.
A connection must exist!

set_exit() has to be called in your script !.
Engine is shut down. Many functions do not work anymore! Check out the tutorial section how to use this function (temp_script.py).

set_status_txt(text) Sets the first line in the console to the string you like.
text should be a unicode string
Same for set_status_txt2(text).

orientation()
Returns 0 if canvas x size is smaller than y size (Portrait mode if fullscreen).
Returns 1 if canvas x size is greater than y size (Landscape mode if fullscreen).
Returns None if glcanvas is None (set_exit() got called).
can be used to find out in what mode the screen orientation is (might be portrait mode even if it returns 1 if canvas is not fullscreen !!!).

ret_running() Returns the var running.
Removed since e_core version 0.04.

Classes:


FogC(object)
create a new FogC class to have access to GL_FOG.
Example:

myfog = FogC()

Functions:
enable() enables Fog (makes it visible)
disables() disables Fog (makes it insible)
color(r, g, b, a) Sets the color values of Fog.
density(d) Sets the density values of Fog.
start(s) Sets the start value of the range in that Fog is visible.
end(e) Sets the end value of the range in that Fog is visible.

Might cause an error on several devices.




Keyboard(object)
Is used to check for keypress (same class as in the python reference book)
keyboard object is automaticly created and ready to use when keyboard_on is 1.
Example:

if keyboard.pressed(EScancodeDownArrow):

#used to check a keypress only once (press and release)
if keyboard.is_down(EScancodeDownArrow):

#used to check if a key is hold
Check also the python reference book.




SensorConnection(object)
Is used to check get accelerometer data
sense_conn object is automaticly created and ready to use when sensor_on is 1.
Possible values go from -8 up to +8 while -4 to +4 are usual values if the phone is not shaken.
Example:

sense_conn = SensorConnection()
sensor_x = sense_conn.delta[0]
sensor_y = sense_conn.delta[1]
sensor_z = sense_conn.delta[2]
sense_conn.cleanup()


Tested on N82 and 5800XM, works with Sensor FW and Sensor API, might require the N95 accelerometer plugin for older Phones. REMEMBER TO CLEAN UP if you exit the script otherwise the sensor might still work in background and wont be usable for a 2nd start of your script!!!




Cam(object)
Stores values for the camera
camera object is automaticly created Example:

camera.x = 1
camera.y = -20
camera.z = 100
camera.pan = 20
camera.roll = -180
camera.tilt = -510

possible values for angles are up to 360, higher or lower values are the same like in the usual range (-1 = 359).




obj(object)
The most important class
creates,loads,handles 3D models. Example:

car = obj()

An model class is now generated and ready to use.
Several attributes and functions can be used now:

Attributes:
index has the objects count stored to the time this obj class got created.
render: If 1 this model gets rendered, if 0 not.
x: X position (default 0).
y: Y position (default 0).
z: Z position (default 0).
pan: pan angle (default 0).
roll: roll angle (default 0).
tilt: tilt angle (default 0).
scale_x: X scale value (default 1 = full size).
scale_y: Y scale value (default 1 = full size).
scale_z: Z scale value (default 1 = full size).
tex_scale_x: X texture scale value (default 1 = full size).
tex_scale_y: Y texture scale value (default 1 = full size).
tex_offset_x: X texture offset value (default 1).
tex_offset_Y: Y texture offset value (default 1).
texcount: texture count.
maskcount: mask count.

Functions:
imp_obj(obj_path, texture_path): Load the modeldata(can take a while). obj_path is a unicode string to the *.obj file and texture_path is a unicode string to the textures folder.
sort_me_in(): loads the model into the render list. Should be called only after imp_obj(). The model is now visible on the screen.
remove_me(): all model data are deleted and the model is removed from the render list.

This class is still under construction and changes can happen often.

Engine files:

• e_imp.py
• e_core.py (beta)
• wlan console.py for PC (python is required)

A small demoscene:

• screenshot:
• demoscene.rar

• write own matrix
• add collision system/detection and ray traces
• maybe port to Maemos PyGTK
• create more tutorials