MoonVideo mk.II 23. August, 2008 Usage instructions ================== First, get the Free Pascal compiler, preferably an up-to-date version. MoonVideo is currently provided in includable format rather than as a unit. So, your program should start with something like this: program MoonVideoTest; uses Windows; {$include moonvid.pas} To initialize MoonVideo, you should set a few variables, then call mv_Init. To gracefully shut down, you should call mv_Quit, preferably via an exit handler. An example exit handler procedure, ReleaseAll, is found at the end of the MoonVideo source. I recommend you modify it to your purposes. An exit handler is installed with the standard AddExitProc() command. Also, your main loop should acknowledge mv_EndProgram, which will become TRUE if the user wants to force a program end. procedure ReleaseAll; Begin if erroraddr <> NIL then writeln('Crash! Runtime error ', exitcode, '!'); mv_Quit; End; Begin // Graceful exit procedure addExitProc(@ReleaseAll); // Initialization variables mv_ProgramName := 'Title Bar Text Here'; mv_OutputMode := 1; mv_OutputSizeCols := 80; mv_OutputSizeRows := 25; mv_TileName := '1020font.bmp'; mv_TileSizeX := 10; mv_TileSizeY := 20; mv_Init; // set up MoonVideo ... // Your main loop Repeat ... Until mv_EndProgram; End. About the initialization variables: mv_ProgramName: the window's title bar for both graphical and console modes. mv_OutputMode: 0 for running in console mode, 1 for graphical tile mode, 2 for a fullscreen graphical tile mode. mv_OutputSizeCols, mv_OutputSizeRows: set the size of the window. There may be limitations under console mode depending on your OS version. mv_TileName: filename of the font bitmap to use. mv_TileSizeX, mv_TileSizeY: dimensions of individual glyphs in the font bitmap. Also, you can edit the palette in the variables mv_Pal[0..255]. The tile information is ignored in console mode. In console mode, ALT+ENTER switches between fullscreen and a windowed console. In graphical tile mode, runtime switching is not supported, though it could be with a little more work. The fullscreen tile mode needs the tile and screen sizes to add up to a supported resolution - for example, if using a 10x20 tileset, you could have a 80x30 character fullscreen window at a resolution of 800x600. Task switching in fullscreen mode works fine. Basic output: Everything is printed out through logical viewports. You need to define their locations and sizes, and get and free memory for their buffers. Generally, you will want to determine the number of windows each program phase uses, initialize them, write into them, and free them upon the end of the phase. Where possible, use MoonVideo functions to interact with the viewports. List of useful functions: mv_ClearWindows Fills the output screen and all logical viewports with black space. mv_CloseWindows Frees all viewport buffers and sets the number of used windows back to 0, for your convenience. Essentially, a reset function. mWrite (targetwindow : byte; x, y : byte; txt : string) Your primary output function, this prints the contents of "txt" in viewport mv_Window[targetwindow], at coordinates x,y. The character number 255 is considered special, and the character after it is read as a command. The numbers 0..9 and capital letters A..V set the text foreground color. The small letters a..h set the background color. An asterisk * followed by two hex numbers sets the lightness level. mv_Scroll (targetwindow : byte) Scrolls the contents of viewport mv_Window[targetwindow] up by a row. mv_ShowPic (filename : string; targetwindow, mode : byte) Loads the BMP file with the given name, and tries to draw it in the viewport mv_Window[targetwindow], scaling to fit automatically. In console mode, the image is always rendered in ASCII; in graphical mode, you can give the "mode" variable as 1 to prefer the full bitmap or as 0 to render in ASCII anyway. mv_DrawWindow (targetwindow : byte; x1, y1, x2, y2 : byte) Flushes the rectangle x1,y1 - x2,y2 within your viewport mv_Window[targetwindow] into the output window. Only call this if you directly change values in the viewport buffer, for example when generating a complex ASCII map without using MWrite. mv_SetCursor (targetwindow : byte; x, y, size : byte) Sets the blinking cursor at x,y within the logical viewport mv_Window[targetwindow]. Size is a value 0..100 representing the height of the cursor caret, with 0 being invisible and 100 covering the entire character cell. mv_GetEvents A special function that keeps in touch with the operating system. Call this regularly if your program is doing a lengthy calculation, to keep the window looking alive throughout. KeyPressed Immediately returns TRUE if any keypresses have been noticed. Readkey Waits until a keypress is in the input buffer, then returns the key as a word value, removing the press from the input buffer. The function will not return until a keypress appears or the program is terminated. In graphical mode, while waiting, this function also draws the blinking cursor caret. The returned value is an ASCII character with some modifiers in the high byte. List of obscure functions, which you should not need to call directly: mv_LoadBMP Loads a BMP file. mv_LoadTiles Calls mv_LoadBMP and processes a font bitmap into memory. mv_ScaleBMP Takes an mv_BMP image pointer and scales it. You should not need to call this directly, unless doing some clever bitmap manipulation. mv_RenderASCII Renders an mv_BMP image into dithered ASCII inside the target viewport. mv_RenderBMP Copies an mv_BMP image inside the target viewport in graphical mode. Other odd functions are also included, such as basic mouse input. Examine the source code for details. The sample below creates a viewport for background art and a smaller one over that. It prints "Hello!" in color 2 (dark green) over the background art. It then enters the main loop, waiting for keypresses. After every keypress, it prints a smiley face (character 1) at random coordinates in the second, smaller viewport. When ESC is pressed, the program quits. -------------------------------------------------------------------- program MoonVideoExample; uses Windows; {$include moonvid.pas} var com : word; procedure ReleaseAll; Begin mv_Quit; End; Begin // Graceful exit procedure addExitProc(@ReleaseAll); // Initialization variables mv_ProgramName := 'MoonVideo example'; mv_OutputMode := 1; mv_OutputSizeCols := 80; mv_OutputSizeRows := 25; mv_TileName := '1020font.bmp'; mv_TileSizeX := 10; mv_TileSizeY := 20; mv_Init; // Set up the viewports with mv_Window[0] do begin // full-window background art locx := 0; locy := 0; SizeX := mv_OutputSizeCols; SizeY := mv_OutputSizeRows; getmem(buffy, sizex * sizey * mv_BlockSize); end; with mv_Window[1] do begin // centered quarter-window locx := mv_OutputSizeCols shr 2; locy := mv_OutputSizeRows shr 2; SizeX := mv_OutputSizeCols shr 1; SizeY := mv_OutputSizeRows shr 1; getmem(buffy, sizex * sizey * mv_BlockSize); end; // We have a total of two viewports mv_NumWindows := 2; // CLS mv_ClearWindows; // Display the background art in viewport 0, mode 1 (graphical) mv_ShowPic('1020font.bmp', 0, 1); // Write a green, faded hello message over the background art. // The empty spaces you see are actually chr(255). mWrite(0, mv_OutputSizeCols shr 1 - 3, 1, 'ÿ2ÿ*40Helÿ*50lÿ*60oÿ*7F!'); // Disable the blinky cursor mv_SetCursor(0, 0, 0, 0); // Main loop Repeat com := ReadKey; if com = 27 then mv_EndProgram := TRUE else mWrite(1, random(mv_Window[1].SizeX), random(mv_Window[1].SizeY), chr(1)); Until mv_EndProgram; // Release the viewports mv_CloseWindows; End. -------------------------------------------------------------------- Go ahead, try the sample program. You will, of course, need the 1020font.bmp file, so download that too. Change the initialization values around to test the console mode and different screen sizes. May your code be fruitful, and not crash upon a multiply! ~ Kirinn/MoonCore