
DIV Games Studio - Dinamic Link Libraries


Este documento presenta la informacin necesaria para construir DLL para DIV.

- Qu es una DLL?

  Una DLL (librera de enlace dinmico), es una parte de un programa que puede
fusionarse con otro programa en tiempo de ejecucin, y que contiene funciones
o procedimientos que sern utilizados por el programa.

- Para que sirven?

  Las DLL sirven para extender el lenguaje de programacin DIV o para modificar
parcialmente su funcionamiento. Estas permiten implementar partes de un
programa en lenguaje C, para despus llamarlas desde el propio DIV.

- Que tipos hay?

  Hay bsicamente tres tipos de DLL que pueden construirse para DIV, las
primeras son los salvapantallas, las segundas las de autocarga y las terceras
las que aaden nuevas funciones al lenguaje.

Instrucciones generales.


Este es un procedimiento asequible nicamente para programadores EXPERTOS en C,
que dispongan del "WATCOM C++ Compiler", es probable que se puedan utilizar
para esto otros compiladores de C, pero nosotros no hemos hecho pruebas con
ellos y, por lo tanto, no podemos asegurar que vayan a funcionar.

Lo primero debe ser aadir el siguiente texto al fichero WLSYSTEM.LNK de Watcom
(que est en el directorio BINB\ de este compilador).

system begin div_dll
    option osname='DIV DLL'
    libpath %WATCOM%\lib386
    libpath %WATCOM%\lib386\dos
    format windows nt dll ^
end

El formato de cdigo empleado es el de las DLL de Windows NT, y esta es la
forma de indicarle a Watcom que genere este tipo de cdigo.

Despus se debe incluir el fichero de cabecera DIV.H, que tambin viene en este
directorio, en l se describen las variables y funciones bsicas sobre las que
se puede interactuar. Adems este fichero contiene una serie de "#define" para
facilitar el acceso a las variables internas de DIV32RUN, que es el mdulo que
contiene todas las funciones y rutinas internas de DIV Games Studio.

Se incluyen varios ejemplos, los mas bsicos son estos tres:

  DEMO0.CPP - Ejemplo bsico de un salvapantallas para los juegos DIV.
  DEMO1.CPP - Ejemplo bsico de una DLL de autocarga.
  DEMO2.CPP - Ejemplo bsico de una DLL de funciones.

Se puede utilizar el archivo de proceso por lotes denominado MAKE.BAT para
compilar estas DLL (si se dispone del Watcom C++ para DOS) que, si no se
produce ningn error, generar la DLL correspondiente (con el mismo nombre).

Normas bsicas.


Las DLL se deben crear en lenguaje C estndar y cuentan con algunas normas
que deben ser respetadas, por ejemplo:

- Se debe incluir la cabecera "div.h", y en el mdulo principal, se debe
realizar la siguiente definicin:

  #define GLOBALS

  antes de incluir esta cabecera (antes del #include "div.h"), para que se
definan las variables, tipos y estructuras bsicas el dicho mdulo (esto es
para cuando se construyan DLL formadas por varios fuentes CPP).

- No es posible utilizar en las mismas las funciones malloc(), free(), fopen()
o fclose(), debindose utilizar en su lugar div_malloc(), div_free(),
div_fopen() y div_fclose(). Estas funciones se comportan exactamente igual que
sus homnimas de C.

- Deben definirse siempre dos funciones, de inicializacin y finalizacin de
la DLL, estas son:

  void __export divmain(COMMON_PARAMS) {
    GLOBAL_IMPORT();
    // Inicializacin
  }

  void __export divend(COMMON_PARAMS) {
    // Finalizacin
  }

- Al margen de las funciones exportadas por DIV, pueden utilizarse la mayora
de funciones estndar de C, incluyendo sus cabeceras correspondientes (sus .h).

Como se utilizan las DLL en el lenguaje?


Las DLL se dividen en dos tipos: las normales y las de autocarga.

Para utilizar las normales, se debe indicar en los juegos una sentencia:

  IMPORT "directorio\nombre.dll";

Justo tras las declaraciones LOCAL del programa principal. No se pueden
utilizar DLL de otros lenguajes.

Las de autocarga pueden utilizarse de la misma forma, o bien simplemente
copindolas al directorio del juego. Se activarn automticamente.

Por ejemplo, si se copia DEMO0.DLL (el salvapantallas ejemplo) en el directorio
de un juego hecho en DIV, este se activar automticamente cada vez que se
ejecute el juego. Para que se activen estas DLL cuando se ejecuta un juego
desde el entorno de DIV, se deben copiar al directorio donde se encuentra
el fichero D.EXE (el ejecutable principal de DIV).

Salva-pantallas (ver demo0.cpp)


Se pueden definir las siguientes funciones en la DLL.

  ss_init() - para inicializar el salvapantallas (cada vez que salte).

  ss_frame() - para realizar operaciones sobre el buffer de vdeo, antes de
  cada volcado.

  ss_end() - para finalizar el salvapantallas.

Se dispone adems de las siguientes variables:

  ss_time - para indicar cada cuanto tiempo debe saltar el salvapantallas,
  en centsimas de segundo (por defecto vale 3000, es decir, cada 30 segundos).

  ss_status - para activar y desactivar el salvapantallas (0-Desactivo/1-Activo).

  ss_exit - se debe poner a 1 en ss_frame() para finalizar forzosamente el
  salvapantallas (el sistema la pondr a 1 cuando se active el teclado, el
  ratn o el joystick).

Se incluye en SS1.CPP un salvapantallas algo ms elaborado que el de DEMO0.CPP,
este simula que la pantalla se funde como si se tratara de un cuadro de granos
de arena.

DLL de autocarga (ver demo1.cpp)


  Estas son DLL que suelen sustituir algunas de las funciones internas de DIV
por otras, las funciones que se pueden definir estn explicadas en DIV.H
(bajo la cabecera "DIV standard Entry-Points").

  Para que una DLL se auto-cargue, se debe incluir la siguiente sentencia
dentro de la funcin div_main():

  Autoload();

  Se incluyen dos DLL de autocarga a modo de ejemplo:

  AGUA.CPP - Simula el efecto de agua en la parte inferior de la pantalla.

  HBOY.CPP - Prubala con cualquier juego DIV! ... ya vers.

DLL de funciones (ver demo2.cpp)


  Es fcil aadir nuevas funciones al lenguaje:

  Primero, se debe crear la nueva funcin en la DLL, esta debe leer sus
parmetros de llamada con getparm() (que devuelve siempre un int), y al
finalizar se debe SIEMPRE retornar un valor con retval() (ver demo2.cpp).

  Despus se debe definir en la DLL la funcin:

  void __export divlibrary(LIBRARY_PARAMS) {
  }

  y dentro de la misma se debe hacer una llamada a COM_export() por cada
funcin que se aada al lenguaje.

  COM_export() recibe tres parmetros, el primero es el nombre que tendr
la funcin en el lenguaje, el segundo el puntero a la misma, y el tercero el
nmero de parmetros de llamada.

  En los programas creados en DIV, tras hacer el IMPORT de la DLL, se podrn
utilizar directamente estas funciones.

Que se puede hacer?


Explorando DIV.H encontrars muchas cosas a las que se puede acceder en las
DLL, se pueden hacer programas que modifiquen las variables de los procesos,
que sustituyan las rutinas de vdeo, que apliquen efectos en ventanas, etc.

Si consigues crear una DLL funcional, no se pone ningn pero a que la
distribuyas como Shareware o como quieras, y si la creas como Freeware ...
pues mejor!.

En cualquier caso, te agradecera que me informaras, a travs de HAMMER o de la
pgina WEB de DIV Games Studio de tus logros personales :-)

Tambin agradecer cualquier sugerencia sobre DIV Games Studio, y si son
realmente prcticas y originales, mejor (no te molestes en pedir funciones
para mdulos de sonido, para 3d, true color ... ya estamos en ello!).

            Gracias por intentarlo!

            Daniel Navarro Medrano, programador principal de DIV Games Studio.
