**************************************** * SNG v1.0 * * Shell avec Niveaux de Gris * * Shell with GrayScale * * * * by Marc Plouhinec * * 15/07/2004 * * url: http://thebestof.vze.com * * Email: mailto://m_plouhinec@yahoo.fr * * * **************************************** translated by pacHa SUMMARY: 1 Introduction 2 Running SNG programs 3 SNG programming 4 How to use sound 5 How to use interrupts 6 Libraries 7 How to use grayscale 8 Hex Editor 9 Debugger 10 Vars List 1 Introduction: --------------- SNG means "Shell avec Niveaux de Gris" (Shell with GrayScale) even if there's no graysacle routines built-in more. SNG is distributed under the GPL license, it means you're allowed to modify/distribute it freely. The shell wants to be easy to use and easy to program for, hence its innovative routines for the TI-82 (libs, interrupts, execution of code in a buffer...) SNG programs will be available on my site (www.thebestof.tk or marcplouhinec.free.fr) and at ticalc.org. 2 Running SNG programs: ----------------------- You can either run SNG programs from the prgm menu (ala BASIC, but be careful : don't call an ASM program from a BASIC one, it will crash), or from a graphical frontend, like the one in the archive. 3 SNG programming: ------------------ The batch file "CompileForSNG.bat" will help you. Edit it by replacing 'test' by the name of your prog. Don't forget to put a '#include "sng10.inc"' at the beginning of your prog. The file sngdef.inc is a list of useful routines, feel free to use it. To use libs, it's a little bit different, go to the section "Libraries". If you dunno asm, you can read a good tutorial at http://karma.ticalc.org). 4 How to use sound ------------------ First of all you need to plug in headphones in the link port (you'll need a small jack adaptator). Inside the prgram, you have to do: LD HL,700 ;HL=tone LD DE,100 ;DE=time CALL BEEP BEEP is a routine you'll find in sngdef.inc Look at "son.asm" for further explanations. 5 How to use interrupts ----------------------- Interrupts are *like* multi-task : one or several routines can be executed while a program is running. Here's how to use them: LD DE,name_of_the_routine_to_execute_as_interrupt CALL NEW_INTERRUPT main_loop: (...) JP NZ,main_loop LD A,0 ;A=# of the interrupt CALL STOP_INTERRUPT RET name_of_the_routine_to_execute_as_interrupt (...) RET Look at "interrupt.asm" for further explanations. 6 Libraries ----------- Libs are packs of routines ready to use. You must initialize them bofore using (SNG adapts the adresses because a lib isn't relocated), you must also un-initialize them when you don't need them more. You can use max 8 libraries at the same time. For the user a lib is a program an other program needs to run properly. For the programmer it's more complicated, but macros have been written so that it's easier. Look at test4 (lib), test(graylib) and test2(graylib). 6.1 Programming with libs ------------------------- A .inc file is associated to a lib, it contains the macros ans the adresses you'll need, you just have to include this file in your program. To use a lib you must initialize it with the macro INITLIB (look at the .inc file), this macro checks if the lib is in the calc and then modifies the adresses ; this macro modifies the accumulator, if everything is ok, a=1, otherwise a=0. Then you need the adress where the lib's code starts, you'll thus use SEARCHLIB that returns that adress in hl. When you want to use a routine of the lib you use the macro LIBCALL(ROUTINE,AdressOfTheLib), this macro is raw, it always works, but it's not optimized, to optimize a call you can store its adress there thanks to STOCKLIBCALL that returns the adress of the call in hl. To 'uninitialize' a lib use STOPLIB. Look at the example test.asm that uses the GRAYLIB lib. 6.2 Programming a lib --------------------- A lib is an asm program that must check some rules for its organisation. The file "help_to_compile_a_lib_for_sng.bat" will help you. A lib must start with : |#include "sng10.inc" | .ORG $0000 followed by a routine table of the lib : | JP ROUTINE1 | JP ROUTINE2 | JP ROUTINE3 Then program these routines as you like, but you must finish each of them by a ret. Here's the idea : |#include "sng10.inc" | .ORG $0000 | | JP ROUTINE1 | JP ROUTINE2 | JP ROUTINE3 | |ROUTINE1: | ~~~~~ | RET | |ROUTINE2: | ~~~~~ | RET | |ROUTINE3: | ~~~~~ | RET | |.END Look at GRAYLIB for a nice example. When the lib is programmed, you have to make a .inc file. Put in it the adresses of your lib's routines and the macros. You MUST put these macros and modify "LIBNAME",0 : |#DEFINE INITLIB LD DE,LibName\ CALL INIT_LIBRARY | |;output: HL = adress of the lib |#DEFINE SEARCHLIB LD HL,LIB_BUFFER\ChercheLib:\ PUSH HL\ PUSH DE\ LD DE,LibName\ LD C,0\ CALL CP_STRING\ OR A\ JR NZ,ChaineTrouvee\ POP DE\ POP HL\ LD BC,10\ ADD HL,BC\ JR ChercheLib\NomLib .DB "NOMLIB",0\ChaineTrouvee:\ POP DE\ POP HL\ LD DE,8\ ADD HL,DE\ CALL LD_HL_MHL | |#DEFINE STOPLIB LD B,0\ LD HL,LIB_BUFFER\ChercheLib2:\ PUSH BC\ PUSH HL\ PUSH DE\ LD DE,NomLib\ LD C,0\ CALL CP_STRING\ OR A\ JR NZ,ChaineTrouvee2\ POP DE\ POP HL\ LD BC,10\ ADD HL,BC\ POP BC\ INC B\ JR ChercheLib2\ChaineTrouvee2:\ POP DE\ POP HL\ POP BC\ LD A,B\ CALL STOP_LIBRARY | |#DEFINE LIBCALL(adress,LibAdress) PUSH BC\ LD HL,(LibAdress)\ LD BC,adress\ ADD HL,BC\ POP BC\ CALL CALL_HL | |#DEFINE STOCKLIBCALL(adress,LibAdress) PUSH BC\ LD HL,(LibAdress)\ LD BC,adress\ ADD HL,BC\ POP BC 7 How to use grayscale ---------------------- To create grayscale, SNG flickers pixels, the images are stored in two planes. white : planes 0 and 1 empty. light gray : plane 0 only dark gray : plane 1 only black : both planes filled In order to use grauscale, you must include the file GRAYLIB.inc in your program then you must allocate 768 bytes for PLANE_1 by using either the macro CREATBUFFERANDTESTMEM1(768,PLANE_1) or CREATEBUFFERANDTESTMEM(768,PLANE_1,LabelNotEnoughMem). Then initialize the lib with : | INITGRAYLIB ; | OR A ; Initializes the lib GRAYLIB, and quits if it's not on calc | RET Z ; | | SEARCHGRAYLIB ; | LD (LibAdress),HL ; Stores the lib's adress in LibAdress Activate grayscale and clear the buffers : | LD DE,PLANE_1 ; | LIBCALL(GRAYSCALE_ON,LibAdress) ; Activates grayscale | | LIBCALL(CLR_BUF,LibAdress) ; Clears the buffers PLANE To de-activate grayscale do : | LIBCALL(GRAYSCALE_OFF,LibAdress) ; de-activates grayscale To un-initialize the lib GRAYLIB do : | STOPGRAYLIB And destroy PLANE_1: | DELBUFFER(768,PLANE_1) Look at "test" and "test2" for further explanations. 8 Hexadecimal editor: ----------------------- SNDEdit has 3 modes of display : -The first one is accessible by hitting the key [Y=], it's the default mode. (Go to adress $2AC0, here are chains of characters of TI OS). The controls: -[(up)], [(down)], [(right)], [(left)] = moves the cursor -[/] = - $1000 -[*] = + $1000 -[-] = - $100 -[+] = + $100 -# and letters (A-F) = modifies an hexadecimal number -The second one is the image mode, it's accessible by hiting the key [WINDOW]. (Go to the program SNG and you'll find the title screen of the shell) Controls: -[(up)], [(down)], [(right)], [(left)] = moves -The third one is the sprite mode, it's accessible by hitting the key [ZOOM]. (Go to address from $590D where are stored the characters) Controls: -[(up)], [(down)], [(right)], [(left)] = moves Important: Between addresses $4000 and $7FFF, it's the ROM page 1. 9 Debugger: -------------- The debuger can disassemble and modifiy a program (Be careful: SNGDeb doesn't know if something is code or data). Controls: -[(up)], [(down)] = moves the cursor -[/] = - $1000 -[*] = + $1000 -[-] = - $100 -[+] = + $100 -[ENTER] = modifies an instruction How to modify an instruction ? You have to select the instruction you want to modify, hit [ENTER], select the size of the instruction and then select it in the list. 10 Listes des variables ----------------------- SNGVAR show var and give some details. This program need GRAYLIB. keys: -Haut select the previous var -Bas select the next var -Enter give some details -Mode quit Send me your questions and suggestions! Please report all the translation errors to pacHa : pacHa-@wanadoo.fr