--------------------------------------------------------------------------------
Codificaciones para las consolas GBA/DS de Nintendo   11-Nov-2011   (c) CUE 2011
--------------------------------------------------------------------------------

Este conjunto de utilidades sirve para codificar datos usados por las consolas y
que suelen provocar una disminucin de tamao, lo que hace que tambin se llamen
compresiones, confundiendo la accin en s misma con el efecto.

Algunas de esas codificaciones pueden ser tratadas por la BIOS, simplificando el
proceso de decodificacin ya que es realizado directamente por la propia consola
sin tener que aadir ms cdigo. Esas codificaciones son RLE, LZSS y Huffman. La
codificacin LZSS se suele llamar equivocadamente LZ77, a pesar de no tener nada
que ver con ella.

Hay juegos que utilizan sus propias codificaciones, y se han aadido tambin por
si se desea trabajar con ellas. A esas codificaciones las he puesto el nombre de
LZX, LZE y BLZ para poder diferenciarlas.

A la LZX se la conoce tambin como ONZ/LZ11 o LZ40, segn la forma de guardar la
informacin (big endian o low endian). Su nombre significa LZ eXtendida, y no es
ms que una mejora de una codificacin ya usada por Nintendo, la llamada 'Yaz0'.

La LZE es una doble LZSS donde se emplea una u otra segn los datos tratados. Su
nombre significa LZ mejorada ('LZ Enhanced' en ingls).

La BLZ, nombre que uso como abreviatura de 'Bottom LZ', es la que se usa con los
overlays de DS y se caracteriza porque puede tener una parte sin codificar antes
de la parte codificada, y sta ltima se debe de tratar empezando desde el final
del fichero (de ah lo de 'Bottom'). Adems, es la extencin usada en los juegos
que la utilizan.

La codificacin LZSS incluye mi propia codificacin, que, aunque es ms lenta en
ejecucin, suele obtener mejores resultados frente al algoritmo tradicional pues
se ha optimizado. Esta codificacin suelo llamarla LZC o LZ-CUE, y el proceso de
decodificacin coincide con el que se usa normalmente, incluido el que se usa en
la BIOS de la consola, por lo que se puede usar sin ningn tipo de problema.

La razn de hacer pblicas estas utilidades es porque actualmente no hay ninguna
que realice algunas codificaciones correctamente, como pasa con Hufmman, la LZ40
o la BLZ. Y eso que hay consolas, como la GBA, que salieron al mercado en 2001 y
usan Huffman. Con estas utilidades ya no habr ningn problema en usar datos que
se hayan modificado y usen alguna de esas codificaciones.

Se incluye el ejecutable de cada una de ellas as como su cdigo fuente en C con
licencia pblica general de GNU (GNU GPL).

Para testear los distintos modos de codificacin se pueden analizar cmo estaban
originalmente los ficheros y cmo quedan despus de decodificarlos y volverlos a
codificar. Es una buena forma de saber si la codificacin se hace correctamente,
que suele ser el proceso que ms dificultades presenta.

Todas las utilidades tienen la misma sintaxis, comenzando con un comando que nos
indica la accin a realizar seguido de uno o varios ficheros, que pueden incluir
comodines en su nombre. Al ser un proceso de lnea de comandos, hay que tener en
cuenta que si un fichero lleva espacios en su nombre deberemos ponerlo encerrado
entre comillas, pues de otra forma se interpretar como dos ficheros diferentes.
Los ficheros que se generan siempre sustituyen a los ficheros originales, por lo
que es aconsejable hacer siempre una copia de todo antes del proceso, lo cual es
responsabilidad del usuario.

Aunque este fichero est en castellano, las utilidades tienen todos sus mensajes
en ingls. Es por ello que se usa '-e' para codificar, de 'encode'. No he tenido
ni tiempo ni ganas de traducir este fichero al ingls, pues me resulta mucho ms
sencillo escribir en mi idioma nativo, as que prefiero explicarlo por si alguno
se sorprende al ver algunas opciones (encode, fast, ...).

No se va a explicar el formato de los datos de cada tipo de codificacin. Es muy
sencillo si se tiene un mnimo de conocimiento, por lo que no hay razn para que
este fichero se alargue ms de lo necesario, a pesar de que alguno de ellos est
explicado por la red de forma extraa (como en el caso de Huffman). No obstante,
quien quiera una explicacin algo ms detallada de los procesos puede buscarme y
pedirla, pero lo har siempre en mi lengua nativa.

Se podra optimizar un poco ms el algoritmo usado en las codificaciones LZE/RLZ
pero no se ha hecho por ahora.


Codificacin RLE
--------------------------------------------------------------------------------

RLE comando fichero [fichero [...]]

Comandos:
  -d ... decodifica un fichero
  -e ... codifica un fichero

Esta codificacin siempre deja los ficheros exactamente iguales a los originales
sin que cambien ni un slo bit. No tiene mayor misterio.


Codificacin LZSS
--------------------------------------------------------------------------------

LZSS comando fichero [fichero [...]]

Comandos:
  -d ..... decodifica un fichero
  -evn ... codifica un fichero, compatible con VRAM, modo normal
  -ewn ... codifica un fichero, compatible con WRAM, modo normal
  -evf ... codifica un fichero, compatible con VRAM, modo rpido (fast)
  -ewf ... codifica un fichero, compatible con WRAM, modo rpido (fast)
  -evo ... codifica un fichero, compatible con VRAM, modo ptimo
  -ewo ... codifica un fichero, compatible con WRAM, modo ptimo

Los ficheros codificados compatibles con VRAM no presentan ningn problema si se
decodifican directamente en la RAM de vdeo de la consola, y son la mejor opcin
pues funcionan tanto en VRAM como en WRAM. Un fichero codificado para WRAM puede
mostrar 'basura' al ser decodificado en VRAM, pues su bus de datos es de 16-bits
y puede provocar un conflicto al intentar leer y escribir al mismo tiempo en una
direccin de memoria. Lo normal es que se usen ficheros compatibles con VRAM.

La opcin 'n' hace que los ficheros codificados queden exactamente iguales a los
ficheros codificados originales.

La opcin 'f' realiza la codificacin mediante bsquedas en rboles binarios, lo
que hace que el proceso sea mucho ms rpido. En teora los ficheros codificados
de esta forma deberan ocupar lo mismo que con la opcin 'n' pero no ocurre as,
ocupando a veces un poco ms y otras veces un poco menos. Es algo pendiente para
mirar, aunque no tiene mayor importancia.

La opcin 'o' es mi propia versin de la codificacin, usando un nuevo algoritmo
para conseguir mejores resultados a costa de emplear ms tiempo, la LZC.

El motivo por el que la utilidad mantiene todos los modos es para que el usuario
pueda ver las diferencias entre ellos: cmo se hace originalmente (normal), cmo
se hace lo mismo pero de forma mucho ms rpica (fast) y cmo se puede codificar
de una forma ms ptima a la que se ha usado siempre (optimal).

Sea cual sea la forma usada al codificar los datos, el proceso de decodificacin
es comn a todas ellas, y se recomienda usar la compatibilidad con VRAM para que
no haya problemas si se decodifican los datos en la memoria de vdeo.


Codificacin Huffman
--------------------------------------------------------------------------------

HUFFMAN comando fichero [fichero [...]]

Comandos:
  -d .... decodifica un fichero
  -e8 ... codifica un fichero, modo 8-bits
  -e4 ... codifica un fichero, modo 4-bits
  -e0 ... codifica un fichero eligiendo el modo que menos ocupe

Los datos codificados siempre quedan idnticos a los originales, pero en el modo
de 8-bits el rbol de cdigos puede ser diferente (la parte inicial de los datos
de hasta 512 bytes). Esto se debe a la reorganizacin de nodos del rbol, que se
hace para evitar ciertos problemas de solapamiento de informacin.

La opcin 'e0' busca cual de los mtodos es el mejor, en trminos de ratio, y lo
elige, descartando el otro.

La utilidad est preparada para trabajar con codificaciones de 2-bis y 1-bit, si
bien slo se han usado como test, a pesar de que el proceso usado es exactamente
el mismo, sin tener que modificar nada.


Codificacin LZX
--------------------------------------------------------------------------------

LZX comando fichero [fichero [...]]

Comandos:
  -d ..... decodifica un fichero
  -evb ... codifica un fichero, compatible con VRAM, modo big-endian
  -ewb ... codifica un fichero, compatible con WRAM, modo big-endian
  -evl ... codifica un fichero, compatible con VRAM, modo low-endian
  -ewl ... codifica un fichero, compatible con WRAM, modo low-endian

Al modo big-endian se le conoce tambin como 'ONZ' o 'LZ11' y al modo low-endian
como 'LZ40', debido a la extensin/cabecera que presenta en sus datos, aunque no
es ms que una mejora de una codificacin usada por Nintendo en otras consolas y
que se conoce como 'Yaz0', pensada para grandes repeticiones de cadenas de datos
dentro del mismo fichero.

Algunos juegos de DS, como 'Ace Attorney Investigations - Miles Edgeworth', usan
la forma big-endian compatible con VRAM, y otros, como 'Golden Sun - Dark Dawn',
usan la forma low-endian compatible con WRAM. Debido a ello, la utilidad permite
elegir el tipo de compatibilidad.

Los ficheros big-endian compatibles con VRAM quedan idnticos a los originales y
los low-endian compatibles con WRAM presentan algunas diferencias en los offsets
que indican la compresin, siendo el resto idntico.


Codificacin LZE
--------------------------------------------------------------------------------

LZE comando fichero [fichero [...]]

Comandos:
  -d ... decodifica un fichero
  -e ... codifica un fichero

Esta codificacin usa dos tipos diferentes de LZSS, con 8  16 bits para indicar
los datos que estn comprimidos, usando la mejor en cada momento.

Esta codificacin suele dejar los ficheros algo ms pequeos que los originales,
y es otra cosa pendiente de mirar para intentar que quede igual.

sta es la codificacin que se usa en los juegos 'Luminous Arc 2-3' de DS.


Codificacin BLZ
--------------------------------------------------------------------------------

BLZ comando fichero [fichero [...]]

Comandos:
  -d .... decodifica un fichero
  -en ... codifica un fichero, modo normal
  -eo ... codifica un fichero, modo ptimo

sta es la codificacin que se emplea con los overlays de DS y en algunos juegos
como 'RPG Maker DS'. Su principal caracterstica es que puede tener una parte no
codificada antes de la parte codificada, que es una LZ normal que comienza desde
el final del fichero hacia el principio.

Esta codificacin suele dejar los ficheros algo ms pequeos que los originales,
siendo otra cosa pendiente de mirar para intentar que quede igual.


--------------------------------------------------------------------------------
Codificaciones para las consolas GBA/DS de Nintendo   11-Nov-2011   (c) CUE 2011
--------------------------------------------------------------------------------
