===========
StructArray
===========

StructArray allows you to perform fast arithmetic operations on
arrays of structured (or unstructured) data.

This library is useful for performing the same operation on every item in an
array.

I've included an example showing a simple particle engine.  It animates 10,000
particles without much trouble.

*This is the "release early" part of the "release early, release often"
equation. It's 80% done.  I just need to finish the other 80%.*

Quick Introduction
==================

Here's a quick introduction to what you can do with it:

>>> import structarray, random

First, create a ``StructArray`` with attributes for position and velocity,
starting with a length of 1000.

>>> particles = structarray.StructArray(('x', 'y', 'dx', 'dy'), size=10000)

Let's give the particles a little random motion.  We can loop through each item
and assign attributes.

>>> for p in particles:
...     p.dx = random.random() * 20 - 10
...     p.dy = random.random() * 50

We can also assign values by index like this:

>>> particles[0].dy = 100

Or we could assign all four values to an index:

>>> particles[0] = (0, 20, 5, 100)             # (x, y, dx, dy)

We can assign a value to every item by assigning it directly to an attribute of
the array:

>>> particles.x = 0          # set x to zero for every item

We can also copy the values of one attribute into another:

>>> particles.y = particles.x

We can also do arithmetic while we are at it:

>>> particles.y = particles.x + 10

So now, how would we go about a simulation loop?

>>> particles.x += particles.dx
>>> particles.y += particles.dy
>>> particles.dy -= 9.81

What's important here is that each of these three operations is applied to
*every* item in the array.  And it all happens in a tight loop in C, so it's
*very* fast.  Even for 10,000 particles.

Sending the data off to the video card is pretty easy:

>>> glVertexPointer(2, GL_FLOAT,
...     particles.get_data_stride(),
...     particles.get_data_addr())

Of course there's more to it than that to get it to display.  Check out the
source distribution for a working example


Download
========

I always upload the latest version to the `StructArray page on PyPI`__.

__ http://cheeseshop.python.org/pypi/StructArray/


Installation
============

Run this command to download and install a precompiled binary.::

    sudo easy_install StructArray

To compile StructArray from source, you need the python development headers
installed.  (This is named ``python-dev`` in debian and ubuntu distributions.
I think rpm distros name it ``python-devel``.)

The C files are included, so you don't need Pyrex installed.  However, if you
*do* have Pyrex, I've only tested it with Pyrex-0.9.6.3.  Results may vary with
older versions.

Installing is just like most any other python module::

    python setup.py build
    sudo python setup.py install


Documentation
=============

You can find the `StructArray reference documentation here`__

__ http://matthewmarshall.org/projects/structarray/docs/structarray/

It's also included when you download the source distribution.

