.. OMGIFOL documentation master file, created by
   sphinx-quickstart on Mon Sep 11 16:59:16 2011.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to OMGIFOL's documentation!
===================================

*Note: this is ridiculously incomplete.*

.. contents::

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

#. Install Python 2.4, which can be downloaded from http://python.org
#. Extract the files in the Omgifol package into a directory named "omg" in pythondir/Lib/site-packages (replace pythondir with the directory where Python is installed).

Optionally:

#. Install the `Python Imaging Library <http://www.pythonware.com/products/pil/>`_. This is required to save or load images.
#. Install Psyco `<http://psyco.sourceforge.net/>`_. This can make Omgifol quite a bit faster, typically 2-10x.

Using Omgifol
=============

At the beginning of an interactive session, or as the first line in a Python script file, enter::

     from omg import *

WAD objects
===========

A ``WAD`` is an abstract representation of a WAD file. A ``WAD`` object can load content from a WAD file, or save content to a WAD file, but is entirely memory-resident.

Loading from WAD files
----------------------

The following are all equivalent::

    a = WAD('wadfile.wad')

    a = WAD(from_file='wadfile.wad')

    f = open('wadfile.wad', 'rb')
    a = WAD(from_file=f)

    a = WAD()
    a.from_file('wadfile.wad')

    f = open('wadfile.wad', 'rb')
    a = WAD()
    a.from_file(f)

You can load more than one file to the same object::

    a = WAD()
    a.from_file(file1)
    a.from_file(file2)
    a.from_file(file3)

In this case, lumps from file2 will overwrite those from file1 with the same name, etc.

Writing to WAD files
--------------------

If *a* is a ``WAD`` instance::

    a.to_file('some_wad.wad')

Accessing lumps
---------------

Lumps are stored in *groups*. Each ``WAD`` holds a number of groups, representing different categories of lumps. Each group is an ordered dictionary; that is, it works just like a Python `dict <http://docs.python.org/tutorial/datastructures.html#dictionaries>`_ object but remembers in which order lumps were inserted

All lumps are instances of the ``Lump`` class; see below for its documentation

To retrieve the sprite called ``CYBR1A`` from the ``WAD`` object *a*, do::

    a.sprites['CYBR1A']

And to replace it with some other lump object called ``some_lump``::

    a.sprites['CYBR1A'] = some_lump

To add a new lump, simply do as above with a lump name that does not yet exist.

Renaming and deleting is done as follows::

    a.sprites.rename('CYBR1A', 'NEW_NAME')
    del a.sprites['CYBR1A']

Lump groups
^^^^^^^^^^^

By default, WADs recognize the following lump groups:

sprites
    Sprite graphics (between S and SS markers)

patches
    Wall graphics (between P and PP markers)

flats
    Flat graphics (between F and FF markers)

colormaps
    Boom colormaps (between C markers)

ztextures
    ZDoom textures (between TX markers)

maps
    Map data

glmaps
    GL nodes map data

music
    Music (all lumps named D_*)

sounds
    Sound effects (all lumps named DS* or DP*)

txdefs
    TEXTURE1, TEXTURE2 and PNAMES

graphics
    Titlepic, status bar, miscellaneous graphics

data
    Everything else

This scheme can be modified if desired; refer to wad.py for the details.

The ``maps`` and ``glmaps`` are special. These do not contain lumps, but additional groups of lumps, one for each map. So if you access E1M1::

    a.maps['E1M1']

you will retrieve a group of lumps containing all the map's data. To retrieve the individual lumps, do::

    a.maps['E1M1']['SIDEDEFS']

etc.

Merging
-------

To merge two ``WADs`` *a* and *b*::

    c = a + b

Note that (for efficiency reasons) this only copies references to lumps, which means that subsequent changes to lumps in *a* or *b* will affect the corresponding lumps in c. To give c its own set of lumps, do::

    c = (a + b).copy()

When lumps in *a* and *b* have the same name, lumps from *b* will replace those from *a*.

It is also possible to merge individual sections::

    a.sprites += b.sprites

Use with care for sections of different types.

Note that some sections do more than just copy over the list of lumps when they merge. For example, adding two *txdefs* sections together will automagically merge the ``TEXTURE1``, ``TEXTURE2`` and ``PNAMES`` lumps. ``txdefs`` also get merged this way when two ``WAD`` objects are merged on the top level.

Lumps
=====

The ``Lump`` class holds a single lump. The class provides the following data and methods:

.data
    The lump's raw data as a string

.to_file(filename)
    Save from a file

.from_file(filename)
    Load from a file

.copy()
    Return a copy

Creating a new lump called 'FOOF' containing the text 'Hello!' and inserting it into a ``WAD`` *w* would be done as follows::

    w.data['FOOF'] = Lump('Hello!')

Graphic lumps
-------------

There are subclasses of ``Lump`` for different types of lumps. Currently, only two of these provide special functionality: ``Graphic`` and ``Flat``.

``Graphic``, used to represent Doom format graphics, provides the following settable attributes:

.offsets
    (x, y) offsets

.x_offset
    x offset

.y_offset
    y offset

.dimensions
    (width, height)

.width
    width in pixels

.height
    height in pixels

``Graphic`` defines the following methods in adddition to those defined by ``Lump``:

.from_raw
    Load from a raw image

.to_raw
    Return the image converted to raw pixels

.from_Image
    Load from a PIL Image instance

.to_Image
    Return the image converted to a PIL image

.translate
    Translate to another palette

For the argument lists used by these functions, refer to the code and the inline documenation in lump.py.

``Flat`` works similarly to ``Graphic``, but handles format conversions slightly differently.

Editors
=======

*Editors* are used to edit lumps or lump groups. They represent lump data with high-level objects and structures, and provide methods to modify the data. The following editors have been implemented so far:

* ``Colormap`` for the COLORMAP lump
* ``Playpal`` for the PLAYPAL lump
* ``Textures`` for TEXTURE1/TEXTURE2/PNAMES
* ``MapEditor`` for maps

All editors provide the following methods::

    .to_lump
    .from_lump

or, if the editor represents more than one lump::

    .to_lumps
    .from_lumps

In the latter case, the editor is initialized with a lump group instead of a single lump.

Map editor
----------

Example (moving one vertex one unit)::

    m = MapEditor(wad.maps["E1M1"])
    m.vertexes[103].x += 1
    wad.maps["E1M1"] = m.to_lumps()

Refer to the source code for more information.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`