kolibrios-fun/programs/develop/libraries/ufmod/readme_es.htm

34 lines
24 KiB
HTML
Raw Normal View History

<html lang=es><head><meta http-equiv=Content-Type content="text/html; charset=windows-1251"><title>uFMOD</title></head><body style='margin:0'><table border=0 cellpadding=0 cellspacing=0 width=100%><tr bgcolor=#E7E7E7 align=center><td height=20 style='color:#708090;font-size:9pt;font-family:Arial,Aerial'>[ <a href='en.htm'>English</a> | Espa&#241;ol | <a href='ru.htm'>Pycc&#954;u&#250;</a> ]<tr bgcolor=#708090><td height=1></table><center><h2 style='font-size:14pt;font-family:Arial,Aerial'>&#956;FMOD v1.25 para KolibriOS</h2></center><div style='font-size:10pt;font-family:Arial,Aerial;text-align:justify;margin:8'><p>uFMOD es una librer&#237;a para reproducir m&#250;sica en formato XM, desarrollada completamente en lenguaje ensamblador. Es perfecta para aplicaciones de tama&#241;o y tiempo cr&#237;tico, libre de defectos audibles, altamente confiable, f&#225;cil de usar, de c&#243;digo fuente abierto y multiplataforma. Permite reproducir ficheros y arreglos est&#225;ticos en memoria. Es capaz de reproducir inclusive ficheros corruptos y/o modificados. Ejemplos de uso disponibles para los siguientes compiladores: FASM, MASM32 y NASM.<p>La versi&#243;n para KolibriOS debe funcionar en cualquier PC, siempre y cuando se cumplan los siguientes requisitos:<ol><li>KolibriOS revisi&#243;n SVN 574 &#243; posterior. Puede descargar el &#250;ltimo distributivo oficial y las actualizaciones SVN de <a href='http://www.kolibrios.org/?&lang=en'>www.kolibrios.org</a>.<li>Una tarjeta de sonido soportada por la librer&#237;a <a href='http://infinity-sound.narod.ru/'>Infinity Sound</a>. Este controlador de audio viene preinstalado en KolibriOS. Actualmente soporta muchas tarjetas de sonido compatibles con AC'97.</ol>Si su m&#225;quina cumple con dichos requisitos pero uFMOD no funciona correctamente, por favor, rep&#243;rtenos este hecho. (Ver <a href='#ci'>informaci&#243;n de contacto</a> en la parte inferior de esta p&#225;gina.)<p><ul><li><a href='#1'>Antes de comenzar</a><li><a href='#2'>Herramientas</a><ul><li><a href='#21'>XMStrip</a><li><a href='#22'>Eff</a></ul><li><a href='#3'>Compilando la librer&#237;a</a><li><a href='#4'>Ejemplos</a><li><a href='#5'>C&#243;mo lograr un ejecutable m&#225;s compacto</a><li><a href='#6'>Preguntas frecuentes</a><li><a href='#7'>Agradecimientos</a></ul><p>&nbsp;<br><a name='1'><b>Antes de comenzar</b></a><p>KolibriOS es un sistema operativo desarrollado en lenguaje ensamblador. Por eso es tan compacto y r&#225;pido. Adem&#225;s, es bastante vers&#225;til, como probablemente ya se habr&#225; podido dar cuenta. Ese tambi&#233;n es el esp&#237;ritu de uFMOD ;)<p>La mayor parte de los pasos descritos a continuaci&#243;n se puede llevar a cabo dir&#233;ctamente en Kolibri. Sin embargo, como muchos programadores principiantes en Kolibri prefieren compilar sus programas en Windows y luego transferirlos a Kolibri para hacer pruebas, vamos a usar compilaci&#243;n cruzada en esta gu&#237;a en aras de generalizar la metodolog&#237;a.<p>&nbsp;<br><a name='2'><b>Herramientas</b></a><p>Hay 2 herramientas gratuitas para usar con uFMOD: XMStrip y Eff. Ninguna de las dos ha sido portada a KolibriOS a&#250;n. Por lo tanto, se recomienda descargar alguno de los otros distributivos uFMOD (Win32, Linux o Unix/BSD) y usar Eff y XMStrip desde otra plataforma. Sin importar la plataforma elegida, ambas herramientas poseen interfaz de usuario dual: consola y gr&#225;fica (GUI). El modo GUI es bastante intuitivo. Vamos a exponer el modo de consola.<p><table border=0 cellpadding=0 cellspacing=0 bgcolor=#708090 style='font-size:9pt;font-family:Arial,Aerial'><tr><td colspan=3 height=1><tr height=18><td style='color:#E7E7E7'><b>&nbsp;SVN&nbsp;</b><td bgcolor=#E7E7E7>&nbsp;<a href='http://ufmod.svn.sourceforge.net/viewvc/ufmod'>C&#243;digo fuente completo disponible</a>&nbsp;<td width=1><tr><td colspan=3 height=1></table><p><a name='21'><b><i>XMStrip</i></b></a> recibe un fichero XM como entrada, modifica su contenido para minimizar el tama&#241;o, sin que esto afecte la calidad del sonido. Concretamente, XMStrip elimina los datos
file - input file name.
output - optional output file name.
options:
/c - clean only (don't strip)
When [output] is not specified, XMSTRIP
attempts to overwrite the input. If file
name contains spaces, enclose it in "".</font></table></center><p>Si no especifica el nombre del fichero de salida, XMStrip intentar&#225; sobreescribir el fichero de entrada. Si el nombre del fichero contiene espacios, enci&#233;rrelo entre comillas dobles ("").<p>Tenga presente, que otros reproductores de XM, probablemente, rechacen los ficheros producidos por XMStrip. Especifique <b>/c</b> para 'recuperar' un fichero as&#237; o s&#237;mplemente para procesar un fichero normal que desea poder usar en otros reproductores de XM.<p><a name='22'><b><i>Eff</i></b></a> es &#250;til para los usuarios avanzados, que desean ahorrar hasta el &#250;ltimo byte en sus aplicaciones. La idea es extraer s&#243;lo aquellas opciones que realmente se van a usar en la aplicaci&#243;n, recompilar la librer&#237;a uFMOD y obtener el menor tama&#241;o posible. Comencemos abriendo una sesi&#243;n de terminal y escribiendo <code>eff /h</code> para obtener el siguiente res&#250;men:<p><center><table border=0 cellpadding=8><tr bgcolor=#000000><td><pre><font color=#FFFFFF> USAGE: eff [options] file
file - input file name
options:
/Dm - generate a masm32/tasm dump
/Dd - generate a Pascal (Delphi) dump
/Dc - generate a C/C++ dump
/Ds - generate an RCDATA resource dump
/Di - disable infoAPI:
uFMOD_GetStats, uFMOD_GetRowOrder,
uFMOD_GetTitle and uFMOD_GetTime
/Dp - disable uFMOD_Pause, uFMOD_Resume
and XM_SUSPENDED
/Dv - disable volume control
/Dj - disable Jump2Pattern
/Df - disable loading XM from file
/Dl - disable XM_NOLOOP
/M - mark & clear unused chunks of
data in a masm32/tasm compatible dump</font></td></tr></table></center><p>Como puede ver, el &#250;ltimo parametro es el nombre del fichero XM que se va a usar con la aplicaci&#243;n. Opciones adicionales:<ul><li><b>/Dm</b> genera un volcado hexadecimal a partir del fichero XM dado, para ser usado en MASM32 o TASM. La sintaxis es compatible con FASM y NASM. Sin embargo, tanto FASM como NASM permiten incluir el contenido de un fichero binario directamente. Es necesario especificar esta opci&#243;n para poder usar <b>/M</b> (ver mas adelante).<li><b>/Dd</b> y <b>/Dc</b> generan volcados para Pascal (Delphi, Kylix, FreePascal) y C/C++ respectivamente.<li><b>/Ds</b> produce un volcado en formato RCDATA, usado en scripts de recursos. No tiene utilidad en KolibriOS.<li>Especifique <b>/Di</b> para deshabilitar todas las funciones informativas: uFMOD_GetStats, uFMOD_GetRowOrder, uFMOD_GetTitle y uFMOD_GetTime. Eliminarlas reduce el tama&#241;o de la librer&#237;a y mejora un poco el rendimiento.<li><b>/Dp</b> elimina las funciones uFMOD_Pause y uFMOD_Resume y hace que uFMOD ignore la bandera XM_SUSPENDED. Si no necesita pausar/reanudar, agregue esta opci&#243;n a la linea de comandos para ahorrar otros tantos bytes.<li>uFMOD_SetVolume no s&#243;lo hace la librer&#237;a m&#225;s grande, sino que tambi&#233;n consume tiempo adicional de CPU. Utilice <b>/Dv</b> para deshabilitar esta funci&#243;n y recuperar algunos bytes y ciclos de reloj ;)<li><b>/Dj</b> deshabilita la funci&#243;n Jump2Pattern. Esta es una funci&#243;n avanzada, no usada en la mayoria de las aplicaciones. Consulte la secci&#243;n <a href='#5'>"C&#243;mo lograr un ejecutable m&#225;s compacto"</a> para mayor informaci&#243;n sobre el uso de Jump2Pattern.<li>&#191;No va a reproducir ficheros - s&#243;lo arreglos est&#225;ticos? Entonces, querr&#225; aprovechar la opci&#243;n <b>/Df</b> para minimizar el tama&#241;o de la librer&#237;a.<li><b>/Dl</b> (L min&#250;scula) hace que la librer&#237;a ignore la bandera XM_NOLOOP (esto tambi&#233;n reduce el tama&#241;o y mejora la eficiencia).<li>Por &#250;ltimo, hay una opci&#243;n de optimizaci&#243;n realmente extrema, disponible s&#243;lo para los programadores en lenguaje ensamblador. En cada fichero XM hay secuencias de bytes que se encuentran reservadas para versiones futuras del formato XM o contienen metadatos (comentarios, publicidad, etc.) <b>/M</b> delimita y resalta estos 'huecos' en el volcado y los habilita para ser usados con mayor utilidad. Por ejemplo, puede almacenar datos y hasta c&#243;digo ejecutable en dichos 'huecos'. El ejemplo src/Masm32/ utiliza esta opci&#243;n.</ul>Si no se presenta error alguno, Eff debe generar un fichero EFF.INC y un volcado hexadecimal, si &#233;ste fue solicitado. Algunos ejemplos (todos son correctos):<p><b>eff /Dmpvjfl /M ejemplo.xm<br>eff /M /Dm /Dp /Dv /Dj /Df /Dl ejemplo.xm<br>eff -M -Dmpvjfl ejemplo.xm</b><p>Cualquiera de estas sentencias produce un volcado en lenguaje ensamblador con todos los 'huecos' delimitados y rellenos con ceros por defecto. El fichero de cabecera EFF.INC recopila los efectos XM que realmente se utilizan en el fichero XM dado, m&#225;s algunas banderas adicionales para deshabilitar las funciones de pausar/reanudar, control de volumen, Jump2Pattern, soporte para ficheros y XM_NOLOOP. Copie EFF.INC en src/ufmodlib/src/ y recompile la librer&#237;a. Consulte la siguiente secci&#243;n para mayor informaci&#243;n sobre c&#243;mo recompilar uFMOD. Acaba de compilar su propia versi&#243;n ultraoptimizada de uFMOD, pero recuerde que &#233;sta contiene un subconjunto de efectos XM. Entonces, &#161;s&#243;lo servir&#225; para reproducir correctamente el fichero XM especificado como par&#225;metro!
<p>&nbsp;<br><a name='3'><b>Compilando la librer&#237;a</b></a><p>Es necesario volver a compilar la librer&#237;a luego de usar <a href='#22'>Eff</a> y para habilitar ciertas funciones especiales (ver tabla <b>Opciones</b> mas adelante). Algunas personas querr&#225;n modificar el c&#243;digo fuente de la librer&#237;a, para poner a prueba sus conocimientos en lenguaje ensamblador o por cualquier otra raz&#243;n. Bueno, la siguiente informaci&#243;n les servir&#225;.<p>El c&#243;digo fuente completo se encuentra en el subdirectorio src/ufmodlib/src/:<ul><li><span style='color:#800080'><b>eff.inc</b></span> es un fichero de cabecera. La herramienta <a href='#22'>Eff</a> genera este fichero. No se recomienda modificarlo directamente, aunque un programador en lenguaje ensamblador rara vez presta atenci&#243;n a esta clase de recomendaciones :)<li><span style='color:#800080'><b>ufmod.inc</b></span> describe detalladamente la API de uFMOD para uso en aplicaciones desarrolladas en ASM/C/C++.<li><span style='color:#800080'><b>ufmod-codec.h</b></span> describe la API en modo AC97SND, el cual resulta &#250;til en reproductores de ficheros de audio, como el AC'97 MP3 player de Serge.<li><span style='color:#008080'><b>core.asm</b></span> contiene la mayor parte del c&#243;digo fuente de uFMOD. Exactamente el mismo fichero aparece en los paquetes de KolibriOS, Unix/BSD, Linux y Win32. Cargar un fichero XM, mezclar los canales de audio, procesar los efectos XM y otras tareas comunes se encuentran implementadas en este fichero.<li><span style='color:#008080'><b>ufmod.asm</b></span> contiene todo el c&#243;digo dependiente del sistema operativo: E/S de ficheros, comunicaci&#243;n con el controlador de audio, etc. El contenido de este fichero var&#237;a en KolibriOS, Unix/BSD, Linux y Win32.<li><span style='color:#008080'><b>fasm.asm</b></span> define las estructuras de datos, constantes y dem&#225;s, usando la sintaxis de Flat Assembler (FASM). Este fichero permite compilar uFMOD con FASM.<li><span style='color:#008080'><b>masm.asm</b></span> define las estructuras de datos, constantes y dem&#225;s, usando la sintaxis de MASM32. Este fichero permite compilar uFMOD con MASM32.<li><span style='color:#008080'><b>nasm.asm</b></span> define las estructuras de datos, constantes y dem&#225;s, usando la sintaxis de Netwide Assembler (NASM). Este fichero permite compilar uFMOD con NASM. </ul>Una vez terminada la modificaci&#243;n del c&#243;digo fuente, si desea recompilar ufmod.obj, abra el fichero de procesamiento por lotes src/ufmodlib/makeobj.bat en un editor de texto plano. Todo lo contenido entre las siguientes l&#237;neas:<pre>rem *** CONFIG START</pre>y<pre>rem *** CONFIG END</pre>es configurable. Verifique los valores en la secci&#243;n <code>Pathes</code>. Una de las opciones dice:<pre>SET UF_NASM=\nasm</pre>Si Ud. tiene instalado NASM, aseg&#250;rese de que el camino all&#237; especificado apunte exactamente a la ubicaci&#243;n de nasmw.exe. Supongamos que NASM se encuentra instalado en <code>D:\TOOLS\NASM</code>. Entonces, vamos a modificar el camino de la siguiente forma:<pre>SET UF_NASM=D:\TOOLS\NASM</pre>No todos los caminos deben ser configurados correctamente para recompilar la librer&#237;a. Por ejemplo, si Ud. prefiere usar FASM como el ensamblador por defecto, no es necesario configurar el camino de NASM. Aseg&#250;rese de que todos los caminos necesarios para recompilar la librer&#237;a sean correctos. Luego, configure las opciones disponibles, de acuerdo con la siguiente tabla:<p><table border=0 cellpadding=4 cellspacing=2 style='font-size:10pt;font-family:Arial,Aerial'><tr bgcolor=#708090 style='color:#E7E7E7;font-weight:bold'><td>Opci&#243;n<td>Descripci&#243;n<td width=200>Valores disponibles<tr valign=top><td>UF_RAMP<td>Esta opci&#243;n controla el acoplador de vol&#250;men (interpolaci&#243;n). Esto sirve para suprimir cierto tipo de defecto de sonido conocido como clic, com&#250;n en m&#250;sica sintetizada. Sin embargo, la interpolaci&#243;n en algunos casos puede generar distorsi&#243;n. STRONG (fuerte) es el valor
<b>Fichero 1 :</b> CABECERA_XM1 P11 P12 P13 I11 I12
<b>Fichero 2 :</b> CABECERA_XM2 P21 P22 P23 P24 I21 I22 I23 I24
<b>Fichero 3 :</b> CABECERA_XM3 P31 I31
</pre><i><b>Leyenda:</b> CABECERA_XMn es la cabecera del n-&#233;simo fichero. Pni es el i-&#233;simo patr&#243;n del n-&#233;simo fichero. Ini es el i-&#233;simo instrumento del n-&#233;simo fichero.</i><p>Primero, vamos a unir los 3 ficheros en uno solo sin compartir los instrumentos:<pre>
<b>Fichero 4 :</b> CABECERA_XM4 P11 P12 P13 P21 P22 P23 P24 P31 I11 I12 I21 I22 I23 I24 I31
</pre>Supongamos que I12 es muy similar o identico a I23 y que I24 es igual que I31. Podemos modificar P2n para hacer que utilicen I12 en vez de I23 y enlazar P31 con I24. Entonces, podremos eliminar I23 e I31:<pre>
<b>Fichero 4 :</b> CABECERA_XM4 P11 P12 P13 P21 P22 P23 P24 P31 I11 I12 I21 I22 I24
</pre>Al final tendr&#225; que modificar los comandos de ciclos y saltos de patrones y las referencias a instrumentos en los "ficheros" 2 y 3. Obviamente, tambi&#233;n es posible unir apenas 2 o m&#225;s de 3 ficheros, aunque el formato XM establece l&#237;mites para el n&#250;mero m&#225;ximo de patrones e instrumentos en un fichero. Esa es, en general, la idea. Es necesario saber usar un tracker para realizar todas estas operaciones sobre un fichero XM. Una vez unidas todas las pistas en un fichero compuesto, podr&#225; iniciar la reproducci&#243;n con un &#250;nico llamado a uFMOD_PlaySong y "activar" las pistas por separado con llamados a uFMOD_Jump2Pattern. Por ejemplo, uFMOD_Jump2Pattern(3) pasaria a reproducir la segunda pista, uFMOD_Jump2Pattern(7) saltaria a la tercera y uFMOD_Jump2Pattern(0) regresaria a la primera. Los indices exactos en cada caso dependen de los patrones asignados con el tracker. El ejemplo <b>jmp2pat</b> emplea esta clase de optimizaci&#243;n.<p>El uso de Jump2Pattern tiene otra ventaja: la conmutaci&#243;n de pistas se realiza mucho m&#225;s r&#225;pido (casi de inmediato) que el proceso habitual de parar la pista actual y cargar una pista nueva. Por lo tanto, puede usar esta t&#233;cnica cuando necesite conmutar las pistas de audio de la manera m&#225;s r&#225;pida posible.<p>&nbsp;<br><a name='6'><b>Preguntas frecuentes</b></a><p><span style='color:#008080'><b>P:</b> &#191;Es uFMOD gratis para cualquier tipo de uso, incluido el comercial?</span><br><b>R:</b> Si, actualmente as&#237; es.<p><span style='color:#008080'><b>P:</b> &#191;En donde puedo conseguir m&#250;sica en formato XM?</span><br><b>R:</b> En <a href='http://modarchive.org/'>The Mod Archive</a> hay un enorme archivo de m&#250;sica gratis en formatos XM, IT, S3M y MOD. Puede usar el <a href='http://www.modplug.com/'>Open Modplug Tracker</a> para convertir ficheros IT, S3M y MOD a formato XM sin perder la calidad. Hay muchos compositores talentosos en la red dispuestos a compartir su m&#250;sica de manera gratuita. &#161;Pero no olvide el copyright!<p><span style='color:#008080'><b>P:</b> &#191;Existe alguna relaci&#243;n entre el proyecto uFMOD y las librer&#237;as FMOD y/o miniFMOD de Firelight Technologies&#174;?</span><br><b>R:</b> Ya no. Hasta el a&#241;o 2004 uFMOD se bas&#243; en el c&#243;digo fuente abierto de la librer&#237;a miniFMOD. Desde ese entonces, el c&#243;digo fuente de uFMOD fue completamente reescrito, optimizado y depurado. Tambi&#233;n fueron agregadas muchas funciones nuevas. Por lo tanto, la versi&#243;n actual de uFMOD no tiene relaci&#243;n alguna con FMOD o miniFMOD.<p><span style='color:#008080'><b>P:</b> Algunas librer&#237;as aseguran incrementar el tama&#241;o del ejecutable en N kilobytes. &#191;En cuanto se incrementa el tama&#241;o de un ejecutable con uFMOD?</span><br><b>R:</b> No es posible establecer un valor exacto, ya que el tama&#241;o depende de muchos factores, a saber: funciones usadas (en especial, si se utiliza la herramienta EFF), c&#243;digo de la aplicaci&#243;n principal, tama&#241;o del fichero XM (cuando el XM es embebido en el ejecutable). Tambi&#233;n depende de las opciones del linker. El ejemplo bin/mini ocupa &#250;nicamente 4.768 bytes sin compresi&#243;n.<p><span style='color:#008080'><b>P:</b> &#191;En d&#243;nde puedo conseguir la especificaci&#243;n oficial del formato XM?</span><br><b>R:</b> No existe especificaci&#243;n oficial actualizada. En cambio, puede estudiar el documento <a href='http://sourceforge.net/project/showfiles.php?group_id=158498&package_id=234625'>"The Unofficial XM File Format Specification: FastTracker II, ADPCM and Stripped Module Subformats"</a> (s&#243;lo en ingl&#233;s). Este documento describe la mayor&#237;a de los aspectos relevantes del formato XM original, al igual que todas las extensiones extraoficiales actualmente soportadas por uFMOD. Los c&#243;digos fuente de ModPlug (en C++) sirven de referencia sobre formatos derivados del MOD, XM, IT, S3M y muchos otros.<p>&nbsp;<br><a name='7'><b>Agradecemos a</b></a><p>antarman, Barracuda,