A.C.E. 1

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 1 / ACE CD 1.iso / files / docs / blitzbad.lha / BlitzBasic2V1.3Part2.doc < prev next >

Wrap

Text File | 1994-12-14 | 112.9 KB | 3,443 lines

Part Two See Also: RESETTIMER Statement: RESETTIMER -------------------------------------------------------------------------- Syntax: ResetTimer Modes: Amiga or Blitz Resets the Amiga's hardware timer to zero "ticks." Read the description for TICKS for more information. Function: JOYC -------------------------------------------------------------------------- Syntax: JoyC (Port) Modes: Amiga or Blitz This function works similarly to the JoyB() function, however it allows you to read the second fire button on two-button joysticks. It will return a 1 if the normal fire button is pressed, a 2 if the second button is pressed, or 3 if both buttons are pressed. Otherwise, it will return a zero (no buttons pressed.) Statement: VWAITPOS -------------------------------------------------------------------------- Syntax: VWaitPos RasterLine Modes: Amiga or Blitz This command is similar to VWAIT, except it allows you to wait for any raster position, not just the top of the display. This is useful for interesting graphics effects. Function: CHECKAGA -------------------------------------------------------------------------- Syntax: CheckAGA Modes: Amiga or Blitz Returns 'TRUE' for AGA machines, otherwise returns 'FALSE.' Using ExecVersion alone will not detect an AGA machine. Kickstart version 39 can and does run on pre-AGA machines, such as the A3000, etc. Therefore, this function is provided to allow you to accurately determine if the AGA chipset is present. Function: PEEKTO$ -------------------------------------------------------------------------- Syntax: PeekTo$ (Address,byte) Modes: Amiga or Blitz PeekTo$() is similar to the Peek$() function, except you can specify what terminator byte to use. With Peek$() the terminator will always be zero, but PeekTo$() will accept any byte value as a terminator. Statement: FORCEPAL -------------------------------------------------------------------------- Syntax: ForcePAL Modes: Amiga or Blitz This command switches the current screen from NTSC to PAL. Statement: FORCENTSC -------------------------------------------------------------------------- Syntax: ForceNTSC Modes: Amiga or Blitz This command switches the current screen from PAL to NTSC. Function: DEPTH -------------------------------------------------------------------------- Syntax: Depth (Bitmap#) Modes: Amiga or Blitz This function returns the depth of the specified Blitz2 bitmap object. Statement: CLICKMOUSE -------------------------------------------------------------------------- Syntax: ClickMouse Modes: Amiga or Blitz Similar to Mousewait, this command halts program execution until the user clicks the mouse. There must must be a separate mouseclick for each CLICKMOUSE command, unlike Mousewait, which will continue through without pausing if the left mouse button was already being pressed. NOTE: Avoid using this command in Amiga mode, as it seriously degrades multitasking. Function: CHIPFREE -------------------------------------------------------------------------- Syntax: ChipFree Modes: Amiga or Blitz This function will return the size, in bytes, of the largest block of free CHIP memory in your system. See Also: FASTFREE , LARGESTFREE Function: FASTFREE -------------------------------------------------------------------------- Syntax: FastFree Modes: Amiga or Blitz This function returns the size of the largest block of FAST memory. Function: LARGESTFREE -------------------------------------------------------------------------- Syntax: LargestFree Modes: Amiga or Blitz This function will return the size of the largest chunk of memory available. This memory may be FAST or CHIP, depending on your system. Function: XOR -------------------------------------------------------------------------- Syntax: Xor (expression,expression) Modes: Amiga or Blitz Returns Exclusive OR of two expressions This function returns the "exclusive-OR" or the two supplied arguments. For example, Xor(255,170) will return 85, and Xor(-1) will return 0. Function: LARGEST.L -------------------------------------------------------------------------- Syntax: Largest.l (Long Integer1,Long Integer2) Modes: Amiga or Blitz This function will return the larger of the two supplied long integers. For example, Largest.l(255,20045) would return 20045. Function: SMALLEST.L -------------------------------------------------------------------------- Syntax: Smallest.l (Long Integer1,Long Integer2) Modes: Amiga or Blitz This function will return the smaller of two supplied long integers. For example, Smallest.l(-999,5) would return -999. Function: LARGEST.Q -------------------------------------------------------------------------- Syntax: Largest.q (Quick1,Quick2) Modes: Amiga or Blitz Identical to the function LARGEST.L except that it accepts quick-type variables or expressions. Function: SMALLEST.Q -------------------------------------------------------------------------- Syntax: Smallest.q (Quick1,Quick2) Modes: Amiga or Blitz Identical to SMALLEST but uses quick-types. Function: LARGEST -------------------------------------------------------------------------- Syntax: Largest (Integer1,Integer2) Modes: Amiga or Blitz This is the fastest "Largest()" function. Note that if passed floats or quick-types, the fraction will be cut off. See description for LARGEST.L and LARGEST.Q LARGESTQ}. Function: SMALLEST -------------------------------------------------------------------------- Syntax: Smallest (Integer1,Integer2) Modes: Amiga or Blitz Like SMALLEST.L and SMALLEST.Q SMALLESTQ}, with less accuracy, but faster than the long-integer and quick-type versions. Function: AVG.L -------------------------------------------------------------------------- Syntax: Avg.l (Long Integer 1,Long Integer 2) Modes: Amiga or Blitz This function will return the average of two long-integers (although the fraction is cut off.) Thus, Avg.l(5,15)=10, and Avg.l(1,2)=1. (Since fractions will be cut off with this function, you may wish to use the quick-type version of this function for more accuracy.) Function: AVG.Q -------------------------------------------------------------------------- Syntax: Avg.q (Quick1,Quick2) Modes: Amiga or Blitz See the description for AVG.L . Function: AVG -------------------------------------------------------------------------- Syntax: Avg (Integer1,Integer2) Modes: Amiga or Blitz See the description for AVG.L . This version is the fastest Avg() function available. Statement: RRANDOMIZE -------------------------------------------------------------------------- Syntax: RRandomize Seed Modes: Amiga or Blitz Given a float-type expression or variable, RRandomize will "seed" the reproducible random number generator. The sequence of pseudo-random numbers produced by RRND will be the same for each seed given it. If you require trully random numbers, try "RRandomize Ticks." Function: RRND -------------------------------------------------------------------------- Syntax: RRnd (Low,High) Modes: Amiga or Blitz Given a range such as (1,6) this function will return a random number based on the seed given it by RRANDOMIZE These sets of "random" numbers can be repeated if you provide the same seed. This can be useful in games, etc. so that using "RRandomize Level#" and then using the RRnd() function to randomly draw the screen, each time the player returns to that particular level, it will be the same. ELMORE ARRAY LIBRARY Function: INDEX -------------------------------------------------------------------------- Syntax: Index List() Modes: Amiga or Blitz Returns index from top of LIST This function will return the current index number of the supplied List() array passed to it. For example, if the list pointer is currently at item 10 in the list, Index would return 10. Statement or Function: REQUEST -------------------------------------------------------------------------- Syntax: Request (Title$,Text$,GadgetText$) Modes: Amiga This command is 2.0-specific. If you're still using 1.3, this command will be unavailable to you. "Request" can be used as both a command or a function. You may provide an optional title (or "" for default window title) a string of text (separated by pipes "|" for each line) and a string containing text for gadgets within the requester. (Separate with "|" if you need more than one.) Used as a command, it merely displays the requester on the current screen and waits for the user to click a gadget. As a function, it will also return a number corresponding to the gadget selected. The gadget on the right should be reserved for negative responses such as "CANCEL" or "NO" and will always return zero. Other gadgets will return values in the order that they appear, beginning with 1 for the first gadget, 2 for the next, etc. Function: ACTIVESCREEN -------------------------------------------------------------------------- Syntax: ActiveScreen Modes: Amiga This function returns ADDRESS of current Intuition screen. This is useful with many Intuition library commands, or to find out information about the currently active screen. Function: SCREENWIDTH -------------------------------------------------------------------------- Syntax: ScreenWidth Modes: Amiga This function returns the pixelwidth of the currently active screen. Function: SCREENHEIGHT -------------------------------------------------------------------------- Syntax: ScreenHeight Modes: Amiga This function returns the pixelheight of the active screen Function: ACTIVEWINDOW -------------------------------------------------------------------------- Syntax: ActiveWindow Modes: Amiga This function returns the address of the current window. This address is mainly used in conjunction with Intuition library commands. Statement or Function: WAITFOR -------------------------------------------------------------------------- Syntax: WaitFor (IDCMP Code) Modes: Amiga Similar to WaitEvent, WAITFOR puts the Amiga to "sleep" until a specified IDCMP code wakes it up. For example, WaitFor $400 would wait until the user strikes a key, and WaitFor $8 would wait until the "close" gadget of the current window was clicked on. These IDCMP codes are additive, so WaitFor $408 would wait until either the "close" gadget was selected, or a key was pressed. Refer to the section on "windows" in the Blitz2 Reference Manual for more information on IDCMP codes. Statement: SHOWREQUESTERS -------------------------------------------------------------------------- Syntax: ShowRequesters OPTION> Modes: Amiga or Blitz OPTIONS: 0=Cancel all requesters 1=Show requesters on Workbench Screen 2=Direct requesters to current window This command allows you to force system requesters like "Please insert volume Foo in any drive" etc. to either be turned off, directed to the workbench, or directed to the current window. When requesters are turned off, the system will behave as if the "CANCEL" gadget was selected for each requester that would otherwise have been displayed. Be sure to re-activate requesters before exiting your program! Function: CHECKSUM -------------------------------------------------------------------------- Syntax: Checksum (String$) Modes: Amiga or Blitz Given a string, Checksum() will return a unique 32-bit integer as a checksum, useful in situations such as serial transfers, etc. to ensure both parties have the same data. Function: CHARCOUNT -------------------------------------------------------------------------- Syntax: CharCount (String$,byte) Modes: Amiga or Blitz This function will return the number of occurances of a given byte within a string. For example, CharCount(text$,32) will count the number of spaces in text$. Function: SEARCHBEGIN -------------------------------------------------------------------------- Syntax: SearchBegin (String$,byte,# from Begin) Modes: Amiga or Blitz Similar to Instr(), SearchBegin will search the given string for the specified byte. For example, SearchBegin(a$,32,1) will return the character position of the first space in a$, while SearchBegin(a$,32,3) will return the position of the third space. If the byte is not found in the string, SearchBegin will return a zero. Function: SEARCHEND -------------------------------------------------------------------------- Syntax: SearchEnd (String$,byte,# from End) Modes: Amiga or Blitz Like SearchBegin() (above) except it searches from the end of the string to the front. For example, SearchBegin(a$,asc("A"),2) will return the character position of the second-from-last letter "A" in the string 'a$.' Function: CIPHER$ -------------------------------------------------------------------------- Syntax: Cipher$ (String$) Modes: Amiga or Blitz The Cipher$() function will encrypt or decrypt a string passed to it. This is especially handy if you don't want users "zapping" your executeable or data files to read it's contents. Note that Cipher$() can only decrypt strings previously created with Cipher$(). Function: NULL -------------------------------------------------------------------------- Syntax: Null (String$) Modes: Amiga or Blitz Many Amiga shared libraries (like the DOS library) require addresses of null-terminated strings as arguments. This function will return a long-integer address of a null-terminated string in memory for such commands. Function: REPEATS -------------------------------------------------------------------------- Syntax: Repeats (String$) Modes: Amiga or Blitz This function will return the number of repeated bytes at the beginning of your string. Thus, Repeats("...Test") would return 3, while Repeats("Example") would return 1. If the string is null, Repeats() will return zero. Function: SPACE$ -------------------------------------------------------------------------- Syntax: SPACE$ (number of spaces) Modes: Amiga or Blitz This function is identical to the Space$ function in many other dialects of BASIC. It will return a string containing the desired number of spaces, making it easier to align tables etc. to the screen or printer. Function: BIN# -------------------------------------------------------------------------- Syntax: Bin# (BinString$) Modes: Amiga or Blitz This function accepts binary value stored in a string and returns the decimal value. Function: HEX# -------------------------------------------------------------------------- Syntax: Hex# (HexString$) Modes: Amiga or Blitz This function accepts hexadecimal value stored in a string and returns the decimal value. Function: INTUITIONBASE -------------------------------------------------------------------------- Syntax: IntuitionBase Modes: Amiga or Blitz Returns Intuition Library base Function: DOSBASE -------------------------------------------------------------------------- Syntax: DosBase Modes: Amiga or Blitz Returns DOS Library base Function: GRAPHICSBASE -------------------------------------------------------------------------- Syntax: GraphicsBase Modes: Amiga or Blitz Returns Graphics Library base Function: FFPBASE -------------------------------------------------------------------------- Syntax: FFPBase Modes: Amiga or Blitz Returns FFP Math Library base Function: DISKFONTBASE -------------------------------------------------------------------------- Syntax: DiskFontBase Modes: Amiga or Blitz Returns DiskFont Library base Function: COMMODITIESBASE -------------------------------------------------------------------------- Syntax: CommoditiesBase Modes: Amiga or Blitz Returns Commodities Library base Function: ICONBASE -------------------------------------------------------------------------- Syntax: IconBase Modes: Amiga or Blitz Returns Icon Library base Function: REXXSYSBASE -------------------------------------------------------------------------- Syntax: RexxSysBase Modes: Amiga or Blitz Returns RexxSys Library base Blitz2 Guidefile Info ------------------------------------------------------------------------- BlitzBasic is copyrighted to Acid Software ========================================== I created this file because I was sick of loading everytime the doc files in the background. So I started to do some typing and block cutting with the original doc files delivered with the libs. I'm glad that these library's are created because they make Blitz2 a lot better and more usefull. You can contact me on internet if needed: j.valks@sbos.nl Special thanks are going to Simon Armstrong of Acid Software for giving me the BUM ascii files. Thanks! Written by: Jurgen Valks (BlitzUser 418) Kerkeind 8a 5293 AB Gemonde (NB) The Netherlands This file is to big now! I gonna make a other file with commands and syntax only... Choose a item: AMIGA SUPPORT LIBRARY (BUM 6) PALETTE LIBRARY ADDITIONS (BUM 5) ANIM LIBRARY (BUM 2) SCREEN LIBRARY ADDITIONS (BUM 5) AREXX LIBRARY (BUM 2) WINDOW LIBRARY ADDITIONS (BUM 5) CONSOLE LIBRARY (BUM 6) NEW SCREEN FLAGS (BUM 4) CRUNCH LIBRARY (BUM 6) ELMORE LIBRARY (BUM 6) AGA PALETTE HANDLING (BUM 4) LOCALE LIBRARY (BUM 6) 3.0 BITMAP HANDLING (BUM 4) MED LIBRARY (BUM 2) NEW GADGET HANDLING (BUM 4) PRINTER LIBARY (BUM 6) SERIALPORT LIBRARY (BUM 2) DATE & TIME COMMANDS (BUM 4) THE NEW DISPLAY LIBRARY (BUM 5) ENVIRONMENT COMMANDS (BUM 4) THE NEW ASL LIBRARY (BUM 5) NEW DRAWING COMMANDS (BUM 4) THE GADTOOLS LIBRARY (BUM 5) MISC ADDITIONS (BUM X) MISC ADDITIONS These are misc commands added in several BUM magazines: BLITCOLL BLOCK EXISTS ILBMVIEWMODE LOADFONT LOADSHAPE REMAP RUNERRSOFF RUNERRSON SETBPLCON0 SHAPEGADGET SHOWBITMAP SORTLIST SPRITEMODE VPOS Statement: SortList -------------------------------------------------------------------------- Syntax: SortList Arrayname() The SortList command is used to rearrange the order of elements in a Blitz2 linked list. The order in which the items are sorted depends on the first field of the linked list type which must be a single integer word. Sorting criteria will be extended in future releases. Statement: LoadFont -------------------------------------------------------------------------- Syntax: LoadFont IntuiFont#,Fontname.font$,Y size [,style] The LoadFont command has been extended with an optional style parameter. The following constants may be combined: #underlined=1 #bold=2 #italic=4 #extended=8 ;wider than normal #colour=64 ;hmm use colour version I suppose Statement: SpriteMode -------------------------------------------------------------------------- Syntax: SpriteMode mode For use with the capabilities of the new Display library SpriteMode is used to define the width of sprites to be used in the program. The mode values 0, 1 and 2 correspong to the widths 16, 32 and 64. Function: Exists -------------------------------------------------------------------------- Syntax: Exists (FileName$) Exists actually returns the length of the file, if 0 the file either does not exist or is empty or is perhaps not a file at all! Hmmm, anyway the following poke turns off the "Please Insert Volume Blah:" requester so you can use Exists to wait for disk changes: Poke.l Peek.l(Peek.l(4)+276)+184,-1 Statements: Runerrson & Runerrsoff -------------------------------------------------------------------------- Syntax: Runerrson & Runerrsoff These two new compiler directives are for enabling and disabling error checking in different parts of the program, they override the settings in Compiler Options. Statement: Block -------------------------------------------------------------------------- Syntax: Block Shape#,X,Y Modes: Amiga/Blitz Description: Block is an extremely fast version of the Blit command with some restrictions. Block should only be used with shapes that are 16,32,48, 64... pixels wide and that are being blitted to an x position of 0,16, 32,48,64... Note that the height and y destination of the shape are not limited by the Block command. Block is intended for use with map type displays. Statement: LoadFont -------------------------------------------------------------------------- Syntax: LoadFont IntuiFont#,Fontname.font$,Y Size Modes: Amiga Description: LoadFont is used to load a font from the fonts: directory. Unlike BlitzFonts any size IntuiFont can be used. The command WindowFont is used to set text output to a certain IntuiFont in a particular Window. Function: VPos (add to chapter 5) -------------------------------------------------------------------------- Syntax: VPos Modes: Amiga/Blitz Description: VPos returns the video's beam vertical position. Useful in both high- speed animation where screen update may need to be synced to a certain video beam position (not just the top of frame as with VWait) and for a fast random nember generator in non frame-synced applications. The Anim.lib The following 4 commands allow the display of Animations in Blitz BASIC. The Animation must be compatible with the DPaint 3 format, this method uses long delta (type 2) compression and does not include any palette changes. The Anim Commands: LOADANIM INITANIM NEXTFRAME FRAMES Anims in nature use a double buffered display, with the addition of the ShowBitMap command to Blitz we can now display (play) Anims in both Blitz and Amiga modes. An Anim consists of an initial frame which needs to be displayed (rendered) using the InitAnim command, subsequent frames are then played by using the NextFrame command. The Frames() function returns the number of frames of an Anim. We have also extended the LoadShape command to support Anim brushes. The following example loads and plays an Anim on a standard Amiga (Intuition) Screen. ; ;play anim example ; ;anim file name could use f$=par$(1) to play anim from cli f$="test.anim" ;open screen same resolution as animation ILBMInfo f$ Screen 0,0,0,ILBMWidth,ILBMHeight,ILBMDepth,ILBMViewMode,"",1,2 ScreensBitMap 0,0 ;an extra bitmap same size as screensbitmap for double buffering BitMap 1,ILBMWidth,ILBMHeight,ILBMDepth ;load anim and set screen colours to same as animation LoadAnim 0,f$,0:Use Palette 0 ;draws first frame to current bitmap (1) and bitmap #0 InitAnim 0,0 While Joyb(0)=0 ShowBitMap db ;tell intuition which bitmap to display VWait ;wait for top of frame db=1-db ;swap current bitmap Use BitMap db NextFrame 0 ;and draw next frame Wend Statement: LoadAnim -------------------------------------------------------------------------- Syntax: LoadAnim Anim#,FileName$[,Palette#] Modes: Amiga Description: The LoadAnim command will create an Anim object and load a DPaint compatible animation. The ILBMInfo command can be used to find the correct screensize and resolution for the anim file. The optional Palette# parameter can be used to load a palette with the anims correct colours. Notes: unlike more advanced anim formats DPaint anims use a single static palette for the entire animation. Like all other Blitz commands that access files the command must be executed in Amiga mode. Statement: InitAnim -------------------------------------------------------------------------- Syntax: InitAnim Anim#[,Bitmap#] Modes: Amiga/Blitz Description: InitAnim renders the first two frames of the Anim onto the current BitMap and the BitMap specified by the second parameter. The second BitMap# parameter is optional, this is to support Anims that are not in a double-buffered format (each frame is a delta of the last frame not from two frames ago). However, the two parameter double buffered form of InitAnim should always be used. (hmmm don't ask me O.K.!) Statement: NextFrame -------------------------------------------------------------------------- Syntax: NextFrame Anim# Modes: Amiga/Blitz Description: NextFrame renders the nextframe of an Anim to the current BitMap. If the last frame of an Anim has been rendered NextFrame will loop back to the start of the Animation. Function: Frames -------------------------------------------------------------------------- Syntax: Frames (Anim#) Description: The Frames() function returns the number of frames in the specified Anim. Statement: ShowBitMap -------------------------------------------------------------------------- Syntax: ShowBitMap [BitMap#] Modes: Amiga Library: ScreensLib Description: The ShowBitMap command is the Amiga-mode version of the Show command. It enables you to change a Screens bitmap allowing double buffered (flicker free) animation to happen on a standard Intuition Screen. Unlike Blitz mode it is better to do ShowBitMap then VWait to sync up with the Amiga's display, this will make sure the new bitmap is being displayed before modifying the previous BitMap. Function: BlitColl -------------------------------------------------------------------------- Syntax: BlitColl (Shape#,x,y) Modes: Amiga/Blitz Description: BlitColl is a fast way of collision detection when blitting shapes. BlitColl returns -1 if a collision occurs, 0 if no collision. A collision occurs if any pixel on the current BitMap is non zero where your shape would have been blitted. ShapesHit is faster but less accurate as it checks only the rectangular area of each shape, where as BlitColl takes into account the shape of the shape and of course1bcan not tell you what shapeyou have collided with. Note: make sure only things that you want to collide with have been drawn on the BitMap e.g. don't Blit your ship and then try BlitColl! Statement: ILBMViewMode -------------------------------------------------------------------------- Syntax: ILBMViewMode Modes: Amiga/Blitz Library: ILBMIFFLib Description: ILBMViewMode returns the viewmode of the file that was processed by ILBMInfo. This is useful for opening a screen in the right mode before using LoadScreen etc. The different values of ViewMode are as follows (add/or them for different combinations): 32768 ($8000) hires 2048 ($0800) ham 128 ($0080) halfbright 4 ($0004) interlace 0 ($0000) lores See Also: ILBMINFO Example: ; ;ilbminfo example ; ;iff file name could use f$=par$(1) to use cli argument f$="test.iff" ;get ilbm information ILBMInfo f$ ;open screen with correct parameters Screen 0,0,0,ILBMWidth,ILBMHeight,ILBMDepth,ILBMViewMode,"",1,2 ;load the iff onto the screens LoadScreen 0,f$,0 ;set the palette Use Palette 0 MouseWait Statement: LoadShape -------------------------------------------------------------------------- Syntax: LoadShape Shape#,Filename$[,Palette#] Modes: Amiga Description: The LoadShape command has now been extended to support anim brushes, if the file is an anim brush the shapes are loaded into consecutive shapes starting with the Shape# provided. Statement: ReMap -------------------------------------------------------------------------- Syntax: ReMap colour#0,colour#1[,Bitmap] Modes: Amiga/Blitz Library: Sis2dLib Description: ReMap is used to change all the pixels on a BitMap in one colour to another colour. The optional BitMap parameter will copy all the pixels in Colour#0 to their new colour on the new bitmap. Statement: ShapeGadget -------------------------------------------------------------------------- Syntax: ShapeGadget GadgetList#,X,Y,Flags,Id,Shape#[,Shape#] Mode: Amiga Description: The ShapeGadget command allows you to create gadgets with graphic imagery. The Shape# parameter refers to a shape object containing the graphics you wish the gadget to contain. The ShapeGadget command has been extended to allow an alternative image to be displayed when the gadget is selected. All other parameters are identical to those in TextGadget. Example: ; ;ShapeGadget example ; Screen 0,3 ScreensBitMap 0,0 ;generate 2 shapes for our shape gadget Cls:Circlef 15,15,15,2:Circlef 8,8,9,5,3:Circlef 24,8,9,2,3 GetaShape 1,0,0,32,32:Circlef 24,8,9,5,3:GetaShape 0,0,0,32,32 ; ShapeGadget 0,148,50,0,1,0,1 TextGadget 0,140,180,0,2,"EXIT" Window 0,0,0,320,200,$100f,"ClickMe",1,2,0 Repeat Until WaitEvent=64 AND GadgetHit=2 Statement: SetBPLCON0 -------------------------------------------------------------------------- Syntax: SetBPLCON0 Default Modes: Amiga/Blitz Description: The SetBPLCON0 command has been added for advanced control of Slice display modes. The BPLCON0 hardware register is on page A4-1 of the reference manual (appendix 4). The bits of interest are as follows: bit#1-ERSY external sync (for genlock enabling) bit#2-LACE interlace mode bit#3-LPEN light pen enable Example: ; ; Blitz Interlaced Slice Example using BPLCON0 ; BitMap 0,640,512,4 ; use SetBPLCON0 4 to set the lace bit on when slice is created SetBPLCON0 4 ;set lace bit BLITZ ;bitmap width=1280 so slice's bitmap modulos miss each 2nd line Slice 0,44,640,256,$fffb,4,8,8,1280,1280 ;cludge the modulo ;every vertical blank either show odd lines or even lines ;depending on the long frame bit of VPOSR hardware register SetInt 5 If Peek($dff004)<0 Show 0,0,0 Else Show 0,0,1 End SetInt ;draw lines to prove it For i=1 To 1000 Line Rnd(640),Rnd(512),Rnd(640),Rnd(512),Rnd(16) Next ; MouseWait Speak Commands The Amiga speech synthesiser can be activated using the following commands. The narrator.device has been upgraded in Workbench2.0 increasing the quality of the speech. With a bit of messing around you can have a lot of fun with the Amiga's 'voice', Also note that these are compatible with the commands used in BlitzUser1's speech program. Speak Commands: SPEAK SETVOICE TRANSLATE$ PHONETICSPEAK VOICELOC Statement: Speak -------------------------------------------------------------------------- Syntax: Speak string$ Modes: Amiga Description: The Speak command will first convert the given string to phonetics and then pass it to the Narrator.Device. Depending on the settings of the Narrator device (see SETVOICE ) the Amiga will "speak" the string you have sent in the familiar Amiga synthetic voice. Example: NPrint "Type something and hit return..." NPrint "(just return to exit)" Repeat a$=Edit$(80) Speak a$ Until a$="" Statement: SetVoice -------------------------------------------------------------------------- Syntax: SetVoice rate,pitch,expression,sex,volume,frequency Modes: Amiga Description: SetVoice alters the sound of the Amiga's speech synthsiser by changing: Rate: measured in words per minute. Default 150, range 40-400. Pitch: the BaseLine pitch in Hz. Default 110, range 65-320 Expression: 0=robot 1=natural 2=manual Sex: 0=male 1=female Volume: 0 to 64 Frequency: samples per second (22200) As the following example shows you could very well rename the Speak command the Sing command! ; ; sing the praises of Blitz BASIC! ; While Joyb(0)=0 Pitch=65+Rnd(255) rate=100+Rnd(200) SetVoice rate,pitch,1,1,64,22200 Speak "BLITZ BASIC" Wend Function: Translate$ -------------------------------------------------------------------------- Syntax: Translate$(string$) Modes: Amiga Description: Translate$() returns the phonetic equivalent of the string for use with the Translate Example: Print "Enter a Sentence ":a$=Edit$(80) NPrint "Phonetic=",Translate$(a$) MouseWait Statement: PhoneticSpeak -------------------------------------------------------------------------- Syntax: PhoneticSpeak phonetic$ Modes: Amiga Description: PhoneticSpeak is similar to the Speak command but should only be passed strings containing legal phonemes such as that produced by the Translate$() function. Function: VoiceLoc -------------------------------------------------------------------------- Syntax: VoiceLoc Modes: Amiga Description: VoiceLoc returns a pointer to the internal variables in the speech synthesiser that enable the user to access new parameters added to the V37 Narrator Device. Formants as referred to in the descriptions are the major vocal tracts and are separated into the parts of speech that produce the bass, medium and trebly sounds. The new paramters are as listed \flags : set to 1 if using extended commands \f0enthusiasm : amount of pitch difference on accents default=32 \f0perturb : amount of "wurble" ie random shake default=0 \f1adj,\f2adj,\f3adj : pitch adjust for low medium and high frequency formants. 0=default \a1adj,\a2adj,\a3adj : amplitude adjust for low medium and high frequency formants 0=default \articulate : speed of articulation 100=default \centralize : amount of the centphon vowel in other vowels 0=default \centphon : a vowel to which all others are adjusted by the \centralize : variable, (limited to IY,IH,EH,AE,AA,AH,AO,OW,UH,ER and UW) \AVbias,\AFbias : amount of bias added to voiced and unvoiced speech sounds, (y,r,w,m vs st,sh,f). \priority : task priority when speaking 100=default Example: ; ; voiceloc() example ; NEWTYPE .voicepars ;new V37 parameters available flags.b f0enthusiasm:f0perturb f1adj:f2adj:f3adj a1adj:a2adj:a3adj articulate:centralize:centphon$ avbias.b:afbias:priority:pad1 End NEWTYPE *v.voicepars=VoiceLoc *v\flags=1 *v\f0enthusiasm=82,90 ;old aged highly excited voice *v\f1adj=0,0,0 ;these are fun to mess with *v\a1adj=0,0,0 *v\centralize=50,"AO" ;no effect *v\articulate=90 *v\avbias=20,20 Speak "COME ON EVERYBODY, DANCE? boom boom !" End The MED commands: LOADMEDMODULE SETMEDVOLUME STARTMEDMODULE GETMEDVOLUME PLAYMED GETMEDNOTE STOPMED GETMEDINSTR JUMPMED SETMEDMASK Statement: LoadMedModule -------------------------------------------------------------------------- Syntax: LoadMedModule MedModule# Name Modes: Amiga Description: The LoadMedModule command loads any version 4 channel Octamed module. The following routines support upto and including version 3 of the Amiganut's Med standard. The number of MedModules loaded in memory at one time is only limited by the MedModules maximum set in the Blitz2 Options requester. Like any Blitz commands that access files LoadMedModule can only be used in AmigaMode. Statement: StartMedModule -------------------------------------------------------------------------- Syntax: StartMedModule MedModule# Modes: Amiga/Blitz Description: StartMedModule is responsible for initialising the module including linking after it is loaded from disk using the LoadMedModule command. It can also be used to restart a module from the beginning. Statement: PlayMed --------------------------------------------------------------------------- Modes: Amiga/Blitz Description: PlayMed is responsible for playing the current MedModule, it must be called every 50th of a second either on an interupt (#5) or after a VWait in a program loop. Statement: StopMed -------------------------------------------------------------------------- Syntax: StopMed Modes: Amiga/Blitz Description: StopMed will cause any med module to stop playing. This not only means that PlayMed will have no affect until the next StartMedModule but silences the audio channels so they are not left ringing as is the effect when PlayMed is not called every vertical blank. Statement: JumpMed -------------------------------------------------------------------------- Syntax: JumpMed Pattern# Modes: Amiga/Blitz Description: JumpMed will change the pattern being played in the current module. Statement: SetMedVolume -------------------------------------------------------------------------- Syntax: SetMedVolume Volume Modes: Amiga/Blitz Description: SetMedVolume changes the overall volume that the Med Library plays the module, all the audio channels are affected. This is most useful for fading out music by slowly decreasing the volume from 64 to 0. Function: GetMedVolume -------------------------------------------------------------------------- Syntax: GetMedVolume Channel# Modes: Amiga/Blitz Description: GetMedVolume returns the current volume setting of the specified audio channel. This is useful for graphic effects that you may wish to sync to certain channels of the music playing. Function: GetMedNote -------------------------------------------------------------------------- Syntax: GetMedNote Channel# Modes: Amiga/Blitz Description: GetMedNote returns the current note playing from the specified channel. As with GetMedVolume this is useful for producing graphics effects synced to the music the Med Library is playing. Function: GetMedInstr -------------------------------------------------------------------------- Syntax: GetMedInstr Channel Modes: Amiga/Blitz Description: GetMedInstr returns the current instrument playing through the specified audio channel. Statement: SetMedMask -------------------------------------------------------------------------- Syntax: SetMedMask Channel Mask Modes: Amiga/Blitz Description: SetMedMask allows the user to mask out audio channels needed by sound effects stopping the Med Library using them. Serial Port Commands The following are a set of commands to drive both the single RS232 serial port on an Amiga as well as supporting multiserial port cards such as the A2232 card. The unit# in the following commands should be set to 0 for the standard RS232 port, unit 1 refers to the default serial port set by the advanced serial preferences program and unit 2 on refer to any extra serial ports available. Serial Port Commands: OPENSERIAL WRITESERIAL WRITESERIALSTRING READSERIAL READSERIALSTRING CLOSESERIAL SETSERIALBUFFER SETSERIALLENS SETSERIALPARAMS SERIALEVENT Function: OpenSerial -------------------------------------------------------------------------- Syntax: OpenSerial device$,unit#,baud,io_serflags Modes: Amiga Description: OpenSerial is used to configure a Serial Port for use. As with OpenFile, OpenSerial is a function and returns zero if it fails. If it succeeds advanced users may note the return result is the location of the IOExtSer structure. Use "serial.device" for device$. The baud rate should be in the range of 110-292,000. The io_serflags parameter includes the following flags: bit7: #serf_xdisabled=128 ; disable xon/xoff bit6: #serf_eofmode=64 ; enable eof checking bit5: #serf_shared=32 ; set if you don't need exclusive use of port bit4: #serf_rad_boogie=16 ; high speed mode bit3: #serf_queuedbrk=8 ; if set, a break command waits for buffer empty bit2: #serf_7wire=4 ; if set, use 7 wire RS232 bit1: #serf_parity_odd=2 ; select odd parity (even if not set) bit0: #serf_parity_on=1 ; enable parity checking Statement: WriteSerial -------------------------------------------------------------------------- Syntax: WriteSerial unit#,byte Modes: Amiga Description: WriteSerial sends one byte to the serial port. Unit# defines which serial port is used. If you are sending characters use the Asc() function to convert the character to a byte e.g. WriteSerial 0,asc("b"). Statement WriteSerialString -------------------------------------------------------------------------- Syntax: WriteSerialString unit#,string Modes: Amiga Description: WriteSerialString is similar to WriteSerial but sends a complete string to the serial port. Function: ReadSerial -------------------------------------------------------------------------- Syntax: ReadSerial (unit#) returns -1 if nothing waiting Modes: Amiga Description: ReadSerial returns the next byte waiting in the serial port's read buffer. If the buffer is empty it returns a -1. It is best to use a word type (var.w=ReadSerial(0)) as a byte will not be able to differentiate between -1 and 255. Function: ReadSerialString -------------------------------------------------------------------------- Syntax: ReadSerialString (unit#) Modes: Amiga Description: ReadSerialString puts the serial port's read buffer into a string, if the buffer is empty the function will return a null string (length=0). Statement: CloseSerial -------------------------------------------------------------------------- Syntax: CloseSerial unit# Modes: Amiga Description: The CloseSerial command will close the port, enabling other programs to use it. Note: Blitz will automatically close all ports that are opened when a program ends. Statement SetSerialBuffer -------------------------------------------------------------------------- Modes: Amiga Description: SetSerialBuffer changes the size of the ports read buffer. This may be useful if your program is not always handling serial port data or is receiving and processing large chunks of data. The smallest size for the internal serial port (unit#0) is 64 bytes. The bufferlength variable is in bytes. Statement: SetSerialLens -------------------------------------------------------------------------- Syntax: SetSerialLens unit#,readlen,writelen,stopbits Modes: Amiga Description: SetSerialLens allows you to change the size of characters read and written by the serial device. Generally readlen=writelen and should be set to either 7 or 8, stopbits should be set to 1 or 2. Default values are 8,8,1. Statement: SetSerialParams -------------------------------------------------------------------------- Syntax: SetSerialParams unit# Modes: Amiga Description: For advanced users, SetSerialParams tells the serial port when parameters are changed. This would only be necesary if they were changed by poking offsets from IOExtSer which is returned by the OpenSerial command. Function: SerialEvent -------------------------------------------------------------------------- Syntax: SerialEvent (unit#) Modes: Amiga Description: SerialEvent is used when your program is handling events from more than 1 source, Windows, ARexx etc. This command is currently not implemented Here's a overview of the Arexx Commands: CREATEMSGPORT REPLYREXXMSG DELETEMSGPORT GETREXXRESULT CREATEREXXMSG GETREXXCOMMAND DELETEREXXMSG GETRESULTSTRING CLEARREXXMSG WAIT FILLREXXMSG REXXEVENT CREATEARGSTRING ISREXXMSG DELETEARGSTRING REXXERROR SENDREXXCOMMAND Function: CreateMsgPort() -------------------------------------------------------------------------- Syntax: PortAddress.l = CreateMsgPort("Name") MODES: Amiga Description: CreateMsgPort is a general Function and not specific to ARexx. CreateMsgPort opens an intuition PUBLIC message port of the name supplied as the only argument. If all is well the address of the port created will be returned to you as a LONGWORD so the variable that you assign it to should be of type long. If you do not supply a name then a private MsgPort will be opened for you. Port.l=CreateMsgPort("PortName") It is important that you check you actually succeeded in opening a port in your program. The following code or something similar will suffice. Port.l=CreateMsgPort("Name") IF Port=0 THEN Error_Routine{} The name you give your port will be the name that Arexx looks for as the HOST address,(and is case sensitive) so take this into consideration when you open your port. NOTE IT MUST BE A UNIQUE NAME AND SHOULD NOT INCLUDE SPACES. Statement: DeleteMsgPort() -------------------------------------------------------------------------- Syntax: DeleteMsgPort Port Modes: Amiga Desription: DeleteMsgPort deletes a MessagePort previously allocated with CreateMsgPort(). The only argument taken by DeleteMsgPort is the address returned by CreateMsgPort(). If the Port was a public port then it will be removed from the public port list. Port.l=CreateMsgPort("Name") IF Port=0 Then End DeleteMsgPort Port Error checking is not critical as if this fails we have SERIOUS PROBLEMS. YOU MUST WAIT FOR ALL MESSAGES FROM AREXX TO BE RECEIVED BEFORE YOU DELETE THE MSGPORT. IF YOU NEGLECT TO DELETE A MSGPORT BLITZ2 WILL DO IT FOR YOU AUTOMATICALLY ON PROGRAM EXIT. Function: CreateRexxMsg() -------------------------------------------------------------------------- Syntax: msg.l=CreateRexxMsg(ReplyPort,"exten","HOST") Modes: Amiga Description: CreateRexxMsg() allocates a special Message structure used to communicate with Arexx. If all is successful it returns the LONGWORD address of this rexxmsg structure. The arguments are ReplyPort which is the long address returned by CreateMsgPort(). This is the Port that ARexx will reply to after it has finished with the message. EXTEN which is the exten name used by any ARexx script you are wishing to run. i.e. if you are attempting to run the ARexx script test.rexx you would use an EXTEN of "rexx". HOST is the name string of the HOST port. Your program is usually the HOST and so this equates to the name you gave your port in CreateMsgPort(). REMEMBER IT IS CASE SENSITIVE. As we are allocating resources error checking is important and can be achieved with the following code: msg.l=CreateRexxMsg(Port,"rexx","HostName") IF msg=0 THEN Error_Routine{} Statement: DeleteRexxMsg -------------------------------------------------------------------------- Syntax: DeleteRexxMsg rexxmsg Modes: Amiga Description: DeleteRexxMsg simply deletes a RexxMsg Structure previously allocated by CreateRexxMsg(). It takes a single argument which is the long address of a RexxMsg structure such as returned by CreateRexxMsg(). msg.l=CreateRexxMsg(Port,"rexx","HostName") IF msg=0 THEN Error_Routine{} DeleteRexxMsg msg Again if you neglect to delete the RexxMsg structure Blitz2 will do this for you on exit of the program. Statement: ClearRexxMsg -------------------------------------------------------------------------- Syntax: ClearRexxMsg1k Modes: Amiga Description: ClearRexxMsg is used to delete and clear an ArgString from one ormore of the Argument slots in a RexxMsg Structure. This is most useful for the more advanced programmer wishing to take advantage of the Arexx #RXFUNC abilities. The arguments are a LONGWORD address of a RexxMsg structure. ClearRexxMsg will always work from slot number 1 forward to 16. Port.l=CreateMsgPort("TestPort") If Port = NULL Then End msg.l=CreateRexxMsg(Port,"vc","TestPort") If msg=NULL Then End SendRexxCommand msg,"open",#RXCOMM|#RXFF_RESULT wait:WHILE GetMsg_(Port) <> msg:Wend ;Wait for reply to come ClearRexxMsg msg ;Delete the Command string we sent NOTE: ClearRexxMsg() is called automatically by RexxEvent() so the need to call this yourself is removed unless you have not sent the RexxMsg to Arexx. Statement: FillRexxMsg() -------------------------------------------------------------------------- Syntax: FillRexxMsg rexxmsg,&FillStruct Modes: Amiga Description: FillRexxMsg allows you to fill all 16 ARGSlots if necessary with either ArgStrings or numerical values depending on your requirement. FillRexxMsg will only be used by those programmers wishing to do more advanced things with Arexx, including adding libraries to the ARexx library list, adding Hosts,Value Tokens etc. It is also needed to access Arexx using the #RXFUNC flag. The arguments are a LONG Pointer to a rexxmsg. The LONG address of a FillStruct NEWTYPE structure. This structure is defined in the Arexx.res and has the following form. NEWTYPE.FillStruct Flags.w ;Flag block Args0.l ; argument block (ARG0-ARG15) Args1.l ; argument block (ARG0-ARG15) Args2.l ; argument block (ARG0-ARG15) Args3.l ; argument block (ARG0-ARG15) Args4.l ; argument block (ARG0-ARG15) Args5.l ; argument block (ARG0-ARG15) Args6.l ; argument block (ARG0-ARG15) Args7.l ; argument block (ARG0-ARG15) Args8.l ; argument block (ARG0-ARG15) Args9.l ; argument block (ARG0-ARG15) Args10.l ; argument block (ARG0-ARG15) Args11.l ; argument block (ARG0-ARG15) Args12.l ; argument block (ARG0-ARG15) Args13.l ; argument block (ARG0-ARG15) Args14.l ; argument block (ARG0-ARG15) Args15.l ; argument block (ARG0-ARG15) EndMark.l ;End of the FillStruct End NEWTYPE The Args?.l are the 16 slots that can possibly be filled ready for converting into the RexxMsg structure. The Flags.w is a WORD value representing the type of LONG word you are supplying for each ARGSLOT (Arg?.l). Each bit in the Flags WORD is representative of a single Args?.l, where a set bit represents a numerical value to be passed and a clear bit represents a string argument to be converted into a ArgString before installing in the RexxMsg. The Flags Value is easiest to supply as a binary number to make the bits visible and would look like this. %0000000000000000 ;This represents that all Arguments are Strings. %0110000000000000 ;This represent the second and third as being integers. FillRexxMsg expects to find the address of any strings in the Args?.l slots so it is important to remember when filling a FillStruct that you must pass the string address and not the name of the string. This is acomplished using the '&' address of operand. So to use FillRexxMsg we must do the following things in our program: 1. Allocate a FillStruct 2. Set the flags in the FillStruct\Flags.w 3. Fill the FillStruct with either integer values or the addresses of our string arguments. 4. Call FillRexxMsg with the LONG address of our rexxmsg and the LONG address of our FillStruct. To accomplish this takes the following code: ;Allocate our FillStruct (called F) DEFTYPE.FillStruct F ;assign some string arguments T$="open":T1$="0123456789" ;Fill in our FillStruct with flags and (&) addresses of our strings F\Flags= %0010000000000000,&T$,&T1$,4 ;Third argument here is an integer (4). Port.l=CreateMsgPort("host") msg.l=CreateRexxMsg(Port,"vc","host") FillRexxMsg msg,&F ;<-3 args see #RXFUNC SendRexxCommand msg,"",#RXFUNC|#RXFF_RESULT|3 Function: CreateArgString() --------------------------------------------------------------------------- Syntax: ArgString.l=CreateArgString("this is a string") Modes: Amiga Description: CreateArgString() builds an ARexx compatible ArgString structure around the provided string. All strings sent to, or received from Arexx are in the form of ArgStrings. See the TYPE RexxARG. If all is well the return will be a LONG address of the ArgString structure. The pointer will actually point to the NULL terminated String with the remainder of the structure available at negative offsets. arg.l=CreateArgString("this is a string") IF arg=0 THEN Error_Routine{}:ENDIF DeleteArgString arg NOTE: An ArgString maybe used as a normal BB2 string variable by simple conversion using PEEK$ i.e. msg$=PEEK$(arg) or perhaps NPRINT PEEK$(arg) NOTE: Most of the BB2 Arexx Functions call this themselves and there will be only limited need for you to access this function. Statement: DeleteArgString -------------------------------------------------------------------------- Syntax:DeleteArgString ArgString Modes: Amiga Description: DeleteArgString is designed to Delete ArgStrings allocated by either Blitz2 or ARexx in a system friendly way. It takes only one argument the LONGWORD address of an ArgString as returned by CreateArgString(). arg.l=CreateArgString("this is a string") IF arg=0 THEN Error_Routine{}:ENDIF DeleteArgString arg NOTE: This function is also called automatically by most of the BB2 Arexx Functions that need it so you should only need to call this on rare occations. Statement: SendRexxCommand -------------------------------------------------------------------------- SendRexxCommand rexxmsg,"commandstring",#RXCOMM|#RXFF_RESULT Modes: Amiga Description: SendRexxCommand is designed to fill and send a RexxMsg structure to ARexx inorder to get ARexx to do something on your behalf. The arguments are as follows; Rexxmsg is the LONGWORD address of a RexxMsg structure as returned by CreateRexxMsg(). Commandstring is the command string you wish to send to ARexx. This is a string as in "this is a string" and will vary depending on what you wish to do with ARexx. Normally this will be the name of an ARexx script file you wish to execute. ARexx will then look for the script by the name as well as the name with the exten added.(this is the exten you used when you created the RexxMsg structure using CreateRexxMsg()). This could also be a string file. That is a complete ARexx script in a single line. ActionCodes are the flag values you use to tell ARexx what you want it to do with the commandstring you have supplied. The possible flags are as follows; COMMAND (ACTION) CODES The command codes that are currently implemented in the resident process are described below. Commands are listed by their mnemonic codes, followed by the valid modifier flags. The final code value is always the logical OR of the code value and all of the modifier flags selected. The command code is installed in the rm_Action field of the message packet. USAGE: RXADDCON This code specifies an entry to be added to the Clip List. Parameter slot ARGO points to the name string,slot ARG1 points to the value string,and slot ARG2 contains the length of the value string. The name and value arguments do not need to be argstrings,but can be just pointers to storage areas. The name should be a null-terminated string,but the value can contain arbitrary data including nulls. USAGE: RXADDFH This action code specifies a function host to be added to the Library List. Parameter slot ARGO points to the (null-terminated) host name string,and slot ARG1 holds the search priority for the node. The search priority should be an integer between 100 and -100 inclusive;the remaining priority ranges are reserved for future extensions. If a node already exists with the same name,the packet is returned with a warning level error code. Note that no test is made at this time as to whether the host port exists. USAGE:RXADDLIB This code specifies an entry to be added to the Library List. Parameter slot ARGO points to a null-terminated name string referring either to a function library or a function host. Slot ARG1 is the priority for the node and should be an integer between 100 and -100 inclusive;the remaining priority ranges are reserved for future extensions. Slot ARG2 contains the entry Point offset and slot ARG3 is the library version number. If a node already exists with the same name,the packet is returned with a warning level error code. Otherwise,a new entry is added and the library or host becomes available to ARexx programs. Note that no test is made at this time as to whether the library exists and can be opened. USAGE:RXCOMM [RXFF_TOKEN] [RXFF_STRING] [RXFF_RESULT] [RXFF_NOIO] Specifies a command-mode invocation of an ARexx program. Parameter slot ARGO must contain an argstring Pointer to the command string. The RXFB_TOKEN flag specifies that the command line is to be tokenized before being passed to the invoked program. The RXFB_STRING flag bit indicates that the command string is a "string file." Command invocations do not normally return result strings,but the RXFB_RESULT flag can be set if the caller is prepared to handle the cleanup associated with a returned string. The RXFB_NOIO modifier suppresses the inheritance of the host's input and output streams. USAGE:RXFUNC [RXFF_RESULT] [RXFF_STRING] [RXFF_NOIO] argcount This command code specifies a function invoction. Parameter slot ARGO contains a pointer to the function name string,and slots ARG1 through ARG15 point to the argument strings,all of which must be passed as argstrings. The lower byte of the command code is the argument count; this count excludes the function name string itself. Function calls normally set the RXFB_RESULT flag,but this is not mandatory. The RXFB_STRING modifier indicates that the function name string is actually a "string file". The RXFB_NOIO modifier suppresses the inheritance of the host's input and output streams. USAGE:RXREMCON This code requests that an entry be removed from the Clip List. Parameter slot ARGO points to the null-terminated name to be removed. The Clip List is searched for a node matching the supplied name,and if a match is found the list node is removed and recycled. If no match is found the packet is returned with a warning error code. USAGE:RXREMLIB This command removes a Library List entry. Parameter slot ARGO points to the null terminated string specifying the library to be removed. The Library List is searched for a node matching the library name,and if a match is found the node is removed and released. If no match is found the packet is returned with a warning error code. The libary node will not be removed if the library is currently being used by an ARexx program. USAGE:RXTCCLS This code requests that the global tracing console be closed. The console window will be closed immediately unless one or more ARexx programs are waiting for input from the console. In this event,the window will be closed as soon as the active programs are no longer using it. USAGE:RXTCOPN This command requests that the global tracing console be opened. Once the console is open,all active ARexx programs will divert their tracing output to the console. Tracing input(for interactive debugging)will also be diverted to the new console. Only one console can be opened; subsequent RXTCOPN requests will be returned with a warning error message. MODIFIER FLAGS Command codes may include modifier flags to select various processing options. Modifier flags are specific to certain commands,and are ignored otherwise. RXFF_NOIO. This modifier is used with the RXCOMM and RXFUNC command codes to suppress the automatic inheritance of the host's input and output streams. RXFF_NONRET. Specifies that the message packet is to be recycled by the resident process rather than being returned to the sender. This implies tht the sender doesn't care about whether the requested action succeeded, since the returned packet provides the only means of acknowledgement. (RXFF_NONRET MUST NOT BE USED AT ANY TIME) RXFF_RESULT. This modifer is valid with the RXCOMM and RXFUNC commands,and requests that the called program return a result string. If the program EXITs(or RETURNs)with an expression,the expression result is returned to the caller as an argstring. This ArgString then becomes the callers responsibility to release. This is automatically accomplished by using GetResultString(). It is therefore imperitive that if you use RXFF_RESULT then you must use GetResultString() when the message packet is returned to you or you will incure a memory loss equal to the size of the ArgString Structure. RXFF_STRING. This modifer is valid with the RXCOMM and RXFUNC command codes. It indicates that the command or function argument(in slot ARGO)is a "string file" rather than a file name. RXFF_TOKEN. This flag is used with the RXCOMM code to request that the command string be completely tokenized before being passed to the invoked program. Programs invoked as commands normally have only a single argument string. The tokenization process uses "white space" to separate the tokens,except within quoted strings. Quoted strings can use either single or double quotes,and the end of the command string(a null character) is considered as an implicit closing quote. EXAMPLES: Port.l=OpenRexxPort("TestPort") If Port = NULL End:EndIf msg.l=CreateRexxMsg(Port,"vc","TestPort") If msg=NULL End:EndIf SendRexxCommand msg,"open",#RXCOMM|#RXFF_RESULT Statement: ReplyRexxMsg -------------------------------------------------------------------------- Syntax: ReplyRexxMsg rexxmsg,Result1,Result2,"ResultString" Modes: Amiga Description: When ARexx sends you a RexxMsg (Other than a reply to yours i.e. sending yours back to you with results) you must repl to the message before ARexx will continue or free that memory associated with that RexxMsg. ReplyRexxMsg accomplishes this for you. ReplyRexxMsg also will only reply to message that requires a reply so you do not have to include message checking routines in your source simply call ReplyRexxMsg on every message you receive wether it is a command or not. The arguments are; rexxmsg is the LONGWORD address of the RexxMsg Arexx sent you as returned by GetMsg_(Port). Result1 is 0 or a severity value if there was an error. Result2 is 0 or an Arexx error number if there was an error processing the command that was contained in the message. ResultString is the result string to be sent back to Arexx. This will only be sent if Arexx requested one and Result1 and 2 are 0. ReplyRexxMsg rexxmsg,0,0,"THE RETURNED MESSAGE" Function: GetRexxResult() -------------------------------------------------------------------------- Syntax: Result.l=GetRexxResult(rexxmsg,ResultNum) Modes: Amiga Description: GetRexxResult extracts either of the two result numbers from the RexxMsg structure. Care must be taken with this Function to ascertain wether you are dealing with error codes or a ResultString address. Basically if result 1 is zero then result 2 will either be zero or contain a ArgString pointer to the ResultString. This should then be obtained using GetResultString(). The arguments to GetRexxResult are; rexxmsg is the LONGWORD address of a RexxMsg structure returned from ARexx. ResultNum is either 1 or 2 depending on wether you wish to check result 1 or result 2. ;print the severity code if there was an error NPrint GetRexxResult(msg,1) ;check for ResultString and get it if there is one IF GetRexxResult(msg,1)=0 IF GetRexxResult(msg,2) THEN GetResultString(msg) ENDIF Function: GetRexxCommand() -------------------------------------------------------------------------- Syntax: String$=GetRexxCommand(msg,1) Modes: Amiga Description: GetRexxCommand allows you access to all 16 ArgString slots in the given RexxMsg. Slot 1 contains the command string sent by ARexx in a command message so this allows you to extract the Command. Arguments are: rexxmsg is a LONGWORD address of the RexxMsg structure as returned by RexxEvent() ARGNum is an integer from 1 to 16 specifying the ArgString Slot you wish to get an ArgString from. BEWARE YOU MUST KNOW THAT THERE IS AN ARGSTRING THERE. Function: GetResultString() -------------------------------------------------------------------------- Syntax: String$=GetResultString(rexxmsg) Modes: Amiga Description: GetResultString allows you to extract the result string returned to you by ARexx after it has completed the action you requested. ARexx will only send back a result string if you asked for one (using the ActionCodes) and the requested action was successful. ;check for ResultString and get it if there is one IF GetRexxResult(msg,1)=0 IF GetRexxResult(msg,2) THEN GetResultString(msg) ENDIF NOTE: Do not attempt to DeleteArgString the result string returned by this function as the return is a string and not an ArgString pointer. BB2 will automatically delete this argstring for you. Statement: Wait -------------------------------------------------------------------------- Syntax: Wait Modes: Amiga Description: Wait halts all program execution until an event occurs that the program is interested in. Any intuition event such as clicking on a gadget in a window will start program execution again. A message arriving at a MsgPort will also start program execution again. So you may use Wait to wait for input from any source including messages from ARexx to your program. Wait should always be paired with EVENT if you need to consider intuition events in your event handler loop. Repeat Wait:rmsg.l=REXXEVENT(Port):ev.l=EVENT IF IsRexxMsg(Rmsg) Process_Rexx_Messages{}:ENDIF ; ; ;Rest of normal intuition event loop statements case etc ; Until ev =$200 Function: RexxEvent() -------------------------------------------------------------------------- Syntax: Rmsg.l=RexxEvent(Port) Modes: Amiga Description: RexxEvent is our Arexx Equivalent of EVENT(). It's purpose is to check the given Port to see if there is a message waiting there for us. It should be called after a WAIT and will either return a NULL to us if there was no message or the LONG address of a RexxMsg Structure if there was a message waiting. Multiple Arexx MsgPorts can be handled using separate calls to RexxEvent(): Wait:Rmsg1.l=RexxEvent(Port1):Rmsg2.l=RexxEvent(Port2):etc RexxEvent also takes care of automatically clearing the rexxmsg if it is our message being returned to us. The argument is the LONG address of a MsgPort as returned by CreateMsgPort(). EXAMPLES: Repeat Wait:Rmsg.l=REXXEVENT(Port):ev.l=EVENT IF IsRexxMsg(Rmsg) Process_Rexx_Messages{}:ENDIF ; ; ;Rest of normal intuition event loop statements case etc Until ev =$200 SEE ALSO: WAIT() , CREATEMSGPORT() Function: IsRexxMsg() -------------------------------------------------------------------------- Syntax: IsRexxMsg(rexxmsg) Modes: Amiga Description: IsRexxMsg tests the argument (a LONGWORD pointer hopefully to a message packet) to see if it is a RexxMsg Packet. If it is TRUE is returned (1) or FALSE if it is not (0). Repeat Wait:Rmsg.l=REXXEVENT:ev.l=EVENT IF IsRexxMsg(Rmsg) Process_Rexx_Messages{}:ENDIF ; ; ;Rest of normal intuition event loop statements case etc Until ev =$200 As the test is non destructive and extensive passing a NULL value or a LONGWORD that does not point to a Message structure (Intuition or Arexx) will safely return as FALSE. SEE ALSO: CREATEREXXMSG() , GETMSG_() Function: RexxError() -------------------------------------------------------------------------- Syntax: ErrorString$=RexxError(ErrorCode) Modes: Amiga Description: RexxError converts a numerical error code such as you would get from GetRexxResult(msg,2) into an understandable string error message. If the ErrorCode is not known to ARexx a string stating so is returned this ensures that this function will always succeed. NPRINT RexxError(5) SEE ALSO: GETREXXRESULT() AGA PALETTE HANDLING Blitz 2's palette object has (again) changed. Palette objects are now capable of containing AGA compatible 24 bit colours. AGA Commands: AGARGB AGAGREEN AGAPALRGB AGABLUE AGARED NEW SCREENFLAGS 3.0 BITMAP HANDLING NEW GADGET HANDLING The new palette objects look like this: NEWTYPE.rgbcomp _red.l ;left justified red component. _green.l ;left justified green component. _blue.l ;left justified blue component. End NEWTYPE NEWTYPE.palettedata _numcols.w ; same as palette/_numcols. _zero.w ; for compatibility with graphics lib ; LoadRGB32. _rgbs.rgbcomp[256] ;256 is the max the amount will actually ;depend upon the highest palette entry. _zero2.l ;for graphics lib too. End NEWTYPE This is the actual object return by Addr Palette(n): NEWTYPE.palette _*data.palettedata ; 00: NULL if no palette present ; else a pointer to palettedata. _numcols.w ; 04: num cols present in palettedata. ; below is colour cycling info. _lowcol.w ; 06: low colour for cycle range. _hicol.w ; 08: high colour for cycle range. _speed.w ; 10: speed of cycle : 16384 = max speed ; sign indicates cycling direction. _var.w ; 12: cvariable speed is added to. ; ; more possible cycling entries.... ; ; 128: sizeof. End NEWTYPE Now for the new AGA functions added to Blitz 2...these will all generate a runtime error if used on a non-AGA Amiga.... Statement: AGARGB -------------------------------------------------------------------------- Syntax: AGARGB Colour Register,Red,Green,Blue Modes: Amiga Description: The AGARGB command is the AGA equivalent of the RGB command. The 'Red', 'Green' and 'Blue' parameters must be in the range 0 through 255, while 'Colour Register' is limited to the number of colours available on the currently used screen. Example: ; ; AGA test ; Screen 0,0,0,1280,512,8,$8024,"SUPER HIRES 256 COLORS",1,2 ScreensBitMap 0,0 For i=0 To 255 AGARGB i,i/2,i/3,i ;shades of purple Circle 640,256,i*2,i,i ;big SMOOTH circles Next MouseWait Statement: AGAPalRGB -------------------------------------------------------------------------- Syntax: AGAPalRGB Palette#,Colour Register,Red,Green,Blue Modes: Amiga Description: The AGAPalRGB command is the AGA equivalent of the PalRGB command. AGAPalRGB allows you to set an individual colour register within a palette object. This command only sets up an entry in a palette object, and will not alter the actual screen palette until a 'Use Palette' is executed. Function: AGARed -------------------------------------------------------------------------- Syntax: AGARed(colour register) Modes: Amiga Description: The AGARed function returns the red component of the specified colour register within the currently used screen. The returned value will be within the range 0 (being no red) through 255 (being full red). Function: AGAGreen -------------------------------------------------------------------------- Syntax: AGAGreen(colour register) Modes: Amiga Description: The AGAGreen function returns the green component of the specified colour register within the currently used screen. The returned value will be within the range 0 (being no green) through 255 (being full green). Function: AGABlue -------------------------------------------------------------------------- Syntax: AGABlue(colour register) Modes: Amiga Description: The AGABlue function returns the blue component of the specified colour register within the currently used screen. The returned value will be within the range 0 (being no blue) through 255 (being full blue). NEW SCREEN FLAGS The superhires viewmode flag $20 is now acceptable, but should always be used in conjunction with the standard hires flag of $8000. The depth of a screen may now be specified up to 8 bitplanes (256 colours) deep (if you've got an AGA machine!). Here's how you would go about opening a super-hires, 256 colour screen: Screen 0,0,0,1280,256,8,$8020,"MyScreen",1,0 3.0 BITMAP HANDLING Blitz 2's Bitmap object has been upgraded to allow for interleaved bitmaps: NewType.Bitmap _ ebwidth[0] ;00: for compatability. _ linemod.w ;00: value to get from one scanline to next. _ height.w ;02: currently pixel height - but open to commodore ; 'enhancement'. _ depth.w ;04: number of bitplanes. _ pad.b[2] ;06: nothing. _ data.l[8] ;08: actual bitplane pointers. _ pad2.b[12] ;40: zilch. _ flags.w ;0=normal bitmap, <0=interleaved. _ bitplanemod.w ;value to get from one bitplane to next. MAY BE 0! _ xclip.w ;pixel width for render clipping _ yclip.w ;pixel height for render clipping _ cclip.w ;number of colours available on bitmap ( = 2^_depth) _ isreal.w ;0=no bitmap here, <0=blitz created bitmap, >0=borrowed ;64: sizeof End NEWTYPE Also, many Blitz2 bitmap related commands have been altered to take this new object into account. NEW GADGET HANDLING A new bit, bit 9, in the 'Flags' parameter of the 'TextGadget' and 'ShapeGadget' commands allow you to create mutually exclusive radio button type gadgets. These gadgets DO NOT require Kickstart 2.0 to operate! Here is an example of setting up some radio button style text gadgets: TextGadget 0,16,16,512,1,"OPTION 1":Toggle 0,1,On TextGadget 0,16,32,512,2,"OPTION 2" TextGadget 0,16,48,512,3,"OPTION 3" The new 'ButtonGroup' command allows you to specify which 'group' a series of button gadgets belong to. See 'ButtonGadget' below. Note that if you are using button gadgets, you SHOULD really toggle ONE of the gadgets 'On' before giving the gadgetlist to a window - as in the example above. Text Gadgets may now be used to create 'cycling' gadgets. Again, these gadgets DO NOT require kickstart 2.0 to work. If you create a text gadget which contains the '|' character in the gadget's text, Blitz 2 will recognize this as a 'cycling' gadget, using the '|' character to separate the options - like this: TextGadget 0,16,16,0,1," HELLO |GOODBYE| SEEYA |" Now, each time this gadget is clicked on, the gadgets text will cycle through 'Hello', 'GOODBYE' and 'SEEYA'. Note that each option is spaced out to be of equal length. This feature should not be used with a GadgetJam mode of 0. NEW GADGETS EXAMPLE NEW GADGET COMMANDS: GAGETSTATUS BUTTONGROUP BUTTONID ENABLE DISABLE SETGADGETSTATUS Function: GadgetStatus -------------------------------------------------------------------------- Syntax: GadgetStatus(GadgetList#,Id) Modes: Amiga Description: GadgetStatus may be used to determine the status of the specified gadget. In the case of 'toggle' type gadget, GadgetStatus will return true (-1) if the gadget is currently on, or false (0) if the gadget is currently off. In the case of a cycling text gadget, GadgetStatus will return a value of 1 or greater representing the currently displayed text within the gadget. Statement: ButtonGroup -------------------------------------------------------------------------- Syntax: ButtonGroup Group Modes: Amiga Description: ButtonGroup allows you to determine which 'group' a number of button type gadgets belong to. Following the execution of ButtonGroup, any button gadgets created will be identified as belonging to the specified group. The upshot of all this is that button gadgets are only mutually exclusive to other button gadgets within the same group. 'Group' must be a positive number greater than 0. Any button gadgets created before a 'ButtonGroup' command is executed will belong to group 1. Function: ButtonId -------------------------------------------------------------------------- Syntax: ButtonId(GadgetList#,ButtonGroup) Modes: Amiga Description: ButtonId may be used to determine which gadget within a group of button type gadgets is currently selected. The value returned will be the GadgetId of the button gadget currently selected. Statements: Enable & Disable -------------------------------------------------------------------------- Syntax: Enable GadgetList#,Id & Disable GadgetList#,Id Modes: Amiga Description: A gadget when disabled is covered by a "mesh" and can not be accessed by the user. The commands Enable and Disable allow the programmer to access this feature of Intuition. Statement: SetGadgetStatus -------------------------------------------------------------------------- Syntax: SetGadgetStatus GadgetList#,Id,Value Modes: Amiga Description: SetGadgetStatus is used to set a cycling text gadget to a particular value, once set ReDraw should be used to refresh the gadget to reflect it's new value. NEW GADGETS EXAMPLE: ; ; new gadget types ; WBStartup:FindScreen 0 ;open on workbench TextGadget 0,32,14,0,0,"CYCLE 1|CYCLE 2|CYCLE 3" ButtonGroup 1 ;first group of radio buttons follows For i=1 To 5 TextGadget 0,32,14+i*14,512,i,"CHANNEL #"+Str$(i) Next ButtonGroup 2 ;second group of radio buttons follows For i=6 To 10 TextGadget 0,32,14+i*14,512,i,"BAND #"+Str$(i) Next Window 0,20,20,160,180,$1008,"GADGET TEST",1,2,0 Repeat ;wait until close window gadget hit ev.l=WaitEvent Until ev=$200 Available commands: SYSTEMDATE DATE$ NUMDAYS DATEFORMAT DAYS MONTHS YEARS WEEKDAY HOURS MINS SECS Function: SystemDate -------------------------------------------------------------------------- Syntax: SystemDate Modes: Amiga Description: SystemDate returns the system date as the number of days passed since 1/1/1978. Example: ; ; date/time test ; Dim d$(6):Restore daynames:For i=0 To 6:Read d$(i):Next Dim m$(12):Restore monthnames:For i=1 To 12:Read m$(i):Next NPrint Date$(SystemDate) NPrint d$(WeekDay)," ",Days," ",m$(Months)," ",Years NPrint Hours,":",Mins,":",Secs NPrint "press mouse to quit" MouseWait daynames: Data$ SUNDAY,MONDAY,TUESDAY,WEDNESDAY Data$ THURSDAY,FRIDAY,SATURDAY monthnames: Data$ JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV,DEC Function: Date$ -------------------------------------------------------------------------- Syntax: Date$ (days) Modes: Amiga Description: Date$ converts the format returned by SystemDate (days passed since 1/1/1978) into a string format of dd/mm/yyyy or mm/dd/yyyy depending on the dateformat (defaults to 0). Function: NumDays -------------------------------------------------------------------------- Syntax: NumDays (date$) Modes: Amiga Description: Numdays converts a Date$ in the above format to the day count format, where numdays is the number of days since 1/1/1978. Statement: DateFormat -------------------------------------------------------------------------- Syntax: DateFormat format# ; 0 or 1 Modes: Amiga Description: DateFormat configures the way both date$ and numdays treat a string representation of the date: 0=dd/mm/yyyy and 1=mm/dd/yyyy Functions: Days Months Years & WeekDay -------------------------------------------------------------------------- Syntax: Days Months Years & WeekDay Modes: Amiga Description: Days Months and Years each return the particular value relevant to the last call to SystemDate. They are most useful for when the program needs to format the output of the date other than that produced by date$. WeekDay returns which day of the week it is with Sunday=0 through to Saturday=6. Functions: Hours Mins & Secs -------------------------------------------------------------------------- Syntax: Hours Mins & Secs Modes: Amiga Description: Hours, Mins and Secs return the time of day when SystemDate was last called. New Environment commands: WBWIDTH WBHEIGHT WBDEPTH WBVIEWMODE PROCESSOR EXECVERSION Added in BUM #4 Functions: WBWidth Height Depth & ViewMode -------------------------------------------------------------------------- Syntax: WBWidth, WBHeight, WBDepth & WBViewMode Modes: Amiga Description: The functions WBWidth, WBHeight, WBDepth & WBViewMode return the width, height,depth & viewmode of the current WorkBench screen as configured by preferences. Functions: Processor & ExecVersion -------------------------------------------------------------------------- Syntax: Processor & ExecVersion Modes: Amiga Description: The two functions Processor & ExecVersion return the relevant information about the system the program is running on. The values returned are as follows: ExecVersion OS Release Processor Part# ------------+------------ -----------+--------------- 33 | 1.2 0 | 68000 34? | 1.3 1 | 68010 36 | 2.0 2 | 68020 39 | 3.0 3 | 68030 | 4 | 68040 New drawing commands included in BUM #4: POLY POLYF BITPLANESBITMAP CLIPBLIT Statement: Poly & Polyf -------------------------------------------------------------------------- Syntax: Poly numpoints,*coords.w,color Polyf numpoints,*coords.w,color[,color2] Modes: Amiga/Blitz Description: Poly & Polyf are bitmap based commands such as Box and Line. They draw polygons (unfilled and filled respectively) using coordinates from an array or newtype of words. Polyf has an optional parameter color2, if used this colour will be used if the coordinates are listed in anti- clockwise order, useful for 3D type applications. If color2= -1 then the polygon is not drawn if the verticies are listed in anti-clockwise order. Example: NEWTYPE .tri:x0.w:y0:x1:y1:x2:y2:End NEWTYPE BLITZ BitMap 0,320,256,3 Slice 0,44,3:Show 0 While Joyb(0)=0 a.tri\x0=Rnd(320),Rnd(256),Rnd(320),Rnd(256),Rnd(320),Rnd(256) Polyf 3,a,1+Rnd(7) Wend Statement: BitPlanesBitMap -------------------------------------------------------------------------- Syntax: BitPlanesBitMap SrcBitMap, DestBitMap, PlanePick Modes: Amiga/Blitz Description: BitPlanesBitMap creates a `dummy' bitmap from the SrcBitMap with only the bitplanes specified by the PlanePick mask. This is useful for shadow effects etc. where blitting speed can be speed up because of the fewer bitplanes involved Statement: ClipBlit -------------------------------------------------------------------------- Syntax: ClipBlit Shape#,X,Y Modes: Amiga/Blitz Description: ClipBlit is the same as the Blit command except ClipBlit will clip the shape to the inside of the used bitmap, all blit commands in Blitz2 are due to be expanded with this feature. Window Library Additions The Commands: WINDOW POSITIONSUPERBITMAP GETSUPERBITMAP PUTSUPERBITMAP WTITLE CLOSEWINDOW WPRINTSCROLL WBLIT BITMAPTOWINDOW EVENTCODE EVENTQUALIFIER Statement: Window -------------------------------------------------------------------------- Syntax: Window Window#,x,y,width,height,flags,title$,dpen,bpen[,gadgetlist# [,bitmap#]] The Window library has been extended to handle super bitmap windows. Super-BitMap windows allow the window to have it's own bitmap which can actually be larger than the window. The two main benefits of this feature are the window's ability to refresh itself and the ability to scroll around a large area "inside" the bitmap. To attach a BitMap to a Window set the SuperBitMap flag in the flags field and include the BitMap# to be attached. Statement: PositionSuperBitMap -------------------------------------------------------------------------- Syntax: PositionSuperBitMap x,y PositionSuperBitMap is used to display a certain area of the bitmap in a super bitmap window. Example: ; ; super bitmap example ; ;create large bimtap for our superbitmap window width=320:height=200 BitMap 0,width,height,2 Circlef 160,100,160,100,1 : Box 0,0,width-1,height-1,3 FindScreen 0 ;two sliders for the borders (see new gadget flags next page) PropGadget 0,3,-8,$18000+4+8+64,1,-20,8 PropGadget 0,-14,10,$11000+2+16+128,2,12,-20 ;reporting of mousemoves means we can track the propgadget as it is moved AddIDCMP $10 SizeLimits 32,32,width+22,height+20 Window 0,0,0,100,100,$1489,"HELLO",1,2,0,0 Gosub drawsuper Repeat ev.l=WaitEvent If ev=2 Then Gosub dosize If ev=$20 Then Gosub domove Until ev=$200 End dosize: SetHProp 0,1,posx/width,InnerWidth/width SetVProp 0,2,posy/height,InnerHeight/height Redraw 0,1:Redraw 0,2:Goto drawsuper domove: Repeat:Gosub drawsuper:Until WaitEvent<>$10:Return drawsuper: ww=width-InnerWidth:hh=height-InnerHeight posx=QLimit(HPropPot(0,1)*(ww+1),0,ww) posy=QLimit(VPropPot(0,2)*(hh+1),0,hh) PositionSuperBitMap posx,posy Return Statement: GetSuperBitMap & PutSuperBitMap -------------------------------------------------------------------------- Syntax: GetSuperBitMap & PutSuperBitMap After rendering changes to a superbitmap window thebitmap attached can also be updated with the GetSuperBitMap. After rendering changes to a bitmap the superbitmap window can be refreshed with the PutSuperBitMap command. Both commands work with the currently used window. Statement: WTitle -------------------------------------------------------------------------- Syntax: WTitle windowtitle$,screentitle$ WTitle is used to alter both the current window's title bar and it's screens title bar. Useful for displaying important stats such as program status etc. Statement: CloseWindow -------------------------------------------------------------------------- Syntax: CloseWindow Window# CloseWindow has been added for convenience. Same as Free Window but a little more intuitive (added for those that have complained about such matters). Statement: WPrintScroll -------------------------------------------------------------------------- Syntax: WPrintScroll WPrintScroll will scroll the current window upwards if the text cursor is below the bottom of the window and adjust the cursor accordingly. Presently WPrintScroll only works with windows opened with the gimme00 flag set (#gimmezerozero=$400). Statement: WBlit -------------------------------------------------------------------------- Syntax: WBlit Shape#,x,y WBlit can be used to blit any shape to the current window. Completely system friendly this command will completely clip the shape to fit inside the visible part of the window. Use GimmeZeroZero windows for clean clipping when the window has title/sizing gadgets. Statement: BitMaptoWindow -------------------------------------------------------------------------- Syntax: BitMaptoWindow Bitmap#,Window#[,srcx,srcy,destx,desty,wid,height] BitMaptoWindow will copy a bitmap to a window in an operating system friendly manner (what do you expect). The main use of such a command is for programs which use the raw bitmap commands such as the 2D and Blit libraries for rendering bitmaps quickly but require a windowing environment for the user inyerface. Functions: EventCode & EventQualifier -------------------------------------------------------------------------- Syntax: EventCode & EventQualifier EventCode returns the actual code of the last Event received by your program, EventQualifier returns the contents of the Qualifier field. Of use with the new GadTools library and some other low level event handling requirements. Gadget Library Additions -------------------------------------------------------------------------- Five new flags have been added when defining gadgets in Blitz2. The first four are for attaching the gadget to one of the windows borders, the GZZGADGET flag is for attaching the gadget to the "outer" rastport/ layer of a gimme zero zero window. #RIGHTBORDER $1000 #LEFTBORDER $2000 #TOPBORDER $4000 #BOTTOMBORDER $8000 #GZZGADGET $10000 PropGadgets have been upgraded to take advantage of the 2.0 "newlook" when/if available. Statement: Toggle -------------------------------------------------------------------------- Syntax: Toggle GadgetList#,Id [,On|Off] The Togggle command in the gadget library has been extended so it will actually toggle a gadgets status if the no On|Off parameter is missing. Screen Library Additions New commands: CLOSESCREEN HIDESCREEN BEEPSCREEN MOVESCREEN SCREENTAGS Statement: CloseScreen -------------------------------------------------------------------------- Syntax: CloseScreen Screen# CloseScreen has been added for convenience. Same as Free Screen but a little more intuitive (especially for those that have complained about such matters (yes we care)). Statement: HideScreen -------------------------------------------------------------------------- Syntax: HideScreen Screen# Move Screen to back of all Screens open in the system. Statement: BeepScreen -------------------------------------------------------------------------- Syntax: BeepScreen Screen# Flash specified screen. Statement: MoveScreen -------------------------------------------------------------------------- Syntax: MoveScreen Screen#,deltax,deltay Move specified screen by specified amount. Good for system friendly special effects. Statement: ScreenTags -------------------------------------------------------------------------- Syntax: ScreenTags Screen#,Title$ [&TagList] or [[,Tag,Data]...] Full access to all the Amiga's new display resoutions is now available in Amiga mode by use of the Screen Tags command. The following tags are of most interest to Blitz2 programmers: (see autodocs) #Left=$80000021 #Top=$80000022 #Width=$80000023 #Height=$80000024 #Depth=$80000025 #DetailPen=$80000026 #_BlockPen=$80000027 #Title=$80000028 #Colors=$80000029 #ErrorCode=$8000002A #Font=$8000002B #SysFont=$8000002C #Type=$8000002D #BitMap=$8000002E #PubName=$8000002F #PubSig=$80000030 #PubTask=$80000031 #DisplayID=$80000032 #DClip=$80000033 #Overscan=$80000034 #Obsolete1=$80000035 #ShowTitle=$80000036 #Behind=$80000037 #_Quiet=$80000038 #AutoScroll=$80000039 #Pens=$8000003A #FullPalette=$8000003B #ColorMapEntries=$8000003C #Parent=$8000003D #Draggable=$8000003E #Exclusive=$8000003F #SharePens=$80000040 #BackFill=$80000041 #_Interleaved=$80000042 #Colors32=$80000043 #VideoControl=$80000044 #FrontChild=$80000045 #BackChild=$80000046 #LikeWorkbench=$80000047 #Reserved=$80000048 ; ; open super wide screen with overscan set for smooth horizontal scroll ; for 2.0 and above with amigalibs.res in resident ; #_BitMap=$8000002E:#_Overscan=$80000034:#_Width=$80000023: #_Height=$80000024 BitMap 0,1280,512,2:Circlef 320,256,256,1 ScreenTags 0,"TEST",#_BitMap,Addr BitMap(0),#_Overscan,1,#_Width,640, #_Height,512 *vp.ViewPort=ViewPort(0) While Joyb(0)=0 VWait *vp\DxOffset=-SMouseX,-SMouseY ScrollVPort_ *vp Wend PALETTE LIBRARY ADDITIONS@{FG TEXT The Palette library has been modified in BUM5 for two reasons. Firstly, it was impossible to perform custom fades using two palettes as the Use Palette command affected the current Slice or Screen. Also with the advent of the Display library the extra properties of the Use Palette command (copy colors to current Slice or Screen) became unwanted. New commands: SHOWPALETTE NEWPALETTEMODE The ShowPalette command has been added to replace the above functionality removed from the Use Palette command. Also, for compatability reasons NewPaletteMode On is used for enabling the above modifications (default is off). Statement: ShowPalette -------------------------------------------------------------------------- Syntax: ShowPalette Palette# ShowPalette replaces Use Palette for copying a palette's colours to the current Screen or Slice. Statement: NewPaletteMode -------------------------------------------------------------------------- Syntax: NewPaletteMode On|Off The NewPaletteMode flag has been added for compatibility with older Blitz2 programs. By setting NewPaletteMode to On the Use Palette command merely makes the specified palette the current object and does not try to copy the colour information to the current Screen or Slice. The New Display Library (#displaylib=143) The new display library is an alternative to the slice library. Instead of extending the slice library for AGA support a completely new display library has been developed. Besides support for extended sprites, super hires scrolling and 8 bitplane displays a more modular method of creating displays has been implemented with the use of CopLists. CopLists need only be initialised once at the start of the program. Displays can then be created using any combination of CopLists and most importantly the CreateDisplay command does not allocate any memory avoiding any memory fragmenting problems. The new display library is for non-AGA displays also. Display Library Commands: INITCOPLIST DISPLAYPALETTE CREATEDISPLAY DISPLAYCONTROLS DISPLAYBITMAP DISPLAYADJUST DISPLAYSPRITE Statement: InitCopList -------------------------------------------------------------------------- Syntax: InitCopList CopList#,ypos,height,type,sprites,colors, customs[,widthadjust] InitCopList is used to create a CopList for use with the CreateDisplay command. The ypos, height parameters define the section of screen. Sprites, colors and customs will allocate instructions for that many sprites (always=8!) colors (yes, as many as 256!) and custom copper instructions (to be used by the new DisplayFX library currently in devlopment). The widthadjust parameter is currently not implemented, for display widths other than standard see the DisplayAdjust command. The following constants make up the type parameter, add the number of bitplanes to the total to make up the type parameter. #smoothscroll=$10 #dualplayfield=$20 #extrahalfbrite=$40 #ham=$80 #lores=$000 #hires=$100 #super=$200 #loressprites=$400 #hiressprites=$800 #supersprites=$c00 #fmode0=$0000 #fmode1=$1000 #fmode2=$2000 #fmode3=$3000 For displays on non-AGA machines only #fmode0 and #loressprites are allowed. More documentation, examples and fixes will be published soon for creating displays. Statement: CreateDisplay -------------------------------------------------------------------------- Syntax: CreateDisplay CopList#[,CopList#..] CreateDisplay is used to setup a new screen display with the new display library. Any number of CopLists can be passed to CreateDisplay although at present they must be in order of vertical position and not overlap. CreateDisplay then links the CopLists together using internal pointers, bitmaps, colours and sprites attached to coplists are not affected. Statement: DisplayBitMap -------------------------------------------------------------------------- Syntax: DisplayBitMap CopList#,bmap[,x,y] [,bmap[,x,y]] The DisplayBitMap command is similar in usage to the slice libraries' show commands. Instead of different commands for front and back playfields and smooth scroll options there is only the one DisplayBitMap command with various parameter options. With AGA machines, the x positioning of lores and hires coplists uses the fractional part of the x parameter for super smooth scrolling.The CopList must be initialised with the smooth scrolling flag set if the x,y parameters are used, same goes for dualplayfield. Statement: DisplaySprite -------------------------------------------------------------------------- Syntax: DisplaySprite CopList#,Sprite#,X,Y,Sprite Channel DisplaySprite is similar to the slice libraries ShowSprite command with the added advantage of super hires positioning and extra wide sprite handling. See also SPRITEMODE . Statement: DisplayPalette -------------------------------------------------------------------------- Syntax: DisplayPalette CopList#,Palette# [,coloroffset] DisplayPalette copies colour information from a Palette to the CopList specified. Statement: DisplayControls -------------------------------------------------------------------------- Syntax: DisplayControls CopList#,BPLCON2,BPLCON3,BPLCON4 DisplayControls allows access to the more remote options available in the Amiga's display system. The following are the most important bits from these registers (still unpublished by Commodore!*()@YU&^) Bit| BPLCON2 | BPLCON3 | BPLCON4 ---+----------------------------+------------------------+------------------ 15 | * | BANK2 * active colour | BPLAM7 xor with | | bank | bitplans ---+----------------------------+------------------------+------------------ 14 | ZDBPSEL2 which bitplane | BANK1 * | BPLAM6 DMA for | for ZD | | altering ---+----------------------------+------------------------+------------------ 13 | ZDBPSEL1 | BANK0 * | BPLAM5 effective | | | colour ---+----------------------------+------------------------+------------------ 12 | ZDBPSEL0 | PF2OF2 col-offset for | BPLAM4 look up | | playfield 2 | ---+----------------------------+------------------------+------------------ 11 | ZDBPEN makes above bp | PF2OF1 | BPLAM3 | hit ZD | | ---+----------------------------+------------------------+------------------ 10 | ZDCTEN ZD is bit#15 of | PF2OF0 | BPLAM2 | colour | | ---+----------------------------+------------------------+------------------ 09 | KILLEHB * | LOCT * palette hi/lo | BPLAM1 | | nibble mode | ---+----------------------------+------------------------+------------------ 08 | RDRAM=0 * | | BPLAM0 ---+----------------------------+------------------------+------------------ 07 | SOGEN ! sync on green + SPRES1 * sprites- | ESPRM7 high order | | resolution | color ---+----------------------------+------------------------+------------------ 06 | PF2PRI H playfield 1/2 | SPRES0 * | ESPRM6 offset for | priority | | even ---+----------------------------+------------------------+------------------ 05 | PF2P2 H playfield/ | BRDRBLANK border is | ESPRM5 sprites | sprite priority | black | ---+----------------------------+------------------------+------------------ 04 | PF2P1 | BRDNTRAN border | ESPRM4 | | hits ZD | ---+----------------------------+------------------------+------------------ 03 | PF1P0 | | OSPRM7 high order | | | color ---+----------------------------+------------------------+------------------ 02 | PF1P2 | ZDCLCKEN ZD=14Mhz | OSPRM6 offset for | | clock | odd ---+----------------------------+------------------------+------------------ 01 | PF1P1 | BRDSPRT sprites in | OSPRM5 sprites | | borders! | ---+----------------------------+------------------------+------------------ 00 | PF1P0 | EXTBLKEN wo blank | OSPRM4 | | outputl | ---+----------------------------+------------------------+------------------ ! - Don't touch H - See standard hardware reference manual * - controlled by display library ZD - any reference to ZD is only a guess (just sold my genlock) Statement: DisplayAdjust -------------------------------------------------------------------------- Syntax: DisplayAdjust CopList#,fetchwid,ddfstrt,ddfstop,diwstrt,diwstop Temporary control of display registers until I get the widthadjust parameter working with InitCopList. Currently only standard width displays are available but you can modify the width manually (just stick a screwdriver in the back of your 1084) or with some knowledge of Commodores AGA circuitry. Anyway, before I start going on about why they couldn't just give us byte per pixel instead of 8 darn bitplanes (CD32 to the rescue!) see the cover disk for more information... The New ASL Library (#myasllib=80) Our policy until now has been that we would only place emphasis on 1.3 compatible commands unless of course they had to do with AGA. Then again I don't even have a LoadWB in my startup-sequence! So instead of complaining I spent an uncomfortable week adding the following 2.0 above specific commands to Blitz2. And as for those with 1.3 and want new ROMS? BURN BABY BURN... The commands: ASLFILEREQUEST ASLFONTREQUEST ASLSCREENREQUEST$ Function: ASLFileRequest$ -------------------------------------------------------------------------- Syntax: ASLFileRequest$ (Title$,Pathname$,Filename$ [,Pattern$] [,x,y,w,h] ) The ASL File Requester is nice. Except for the highlight bar being invisible on directories you get to use keyboard for everything, stick in a pattern$ to hide certain files and of course you get what ever size you want. I made it call the Blitz2 file requester if the program is running under 1.3 (isn't that nice!). There is a fix that patches the ReqTools file requester but that doesn't have the date field. I couldn't get the Save-Only tag or the "Create Directory" option working maybe next upgrade. EXAMPLE: MaxLen pa$=192 MaxLen fi$=192 FindScreen 0 f$=ASLFileRequest$("test",pa$,fi$,"#?.bb",0,0,640,256) If f$ NPrint f$ Else NPrint "failed" EndIf MouseWait Function: ASLFontRequest -------------------------------------------------------------------------- Syntax: ASLFontRequest (enable_flags) The ASL Font Requester is also pretty useful. The flags parameter enables the user to modify the following options: #pen=1:#bckgrnd=2:#style=4:#drawmode=8:#fixsize=16 It doesn't seem to handle colour fonts, no keyboard shortcuts so perhaps patching ReqTools is an option for this one. The following code illustrates how a .fontinfo structure is created by a call to ASLFontRequest (just like programming in a high level language man!). EXAMPLE: NEWTYPE .fontinfo name.s ysize.w style.b:flags.b pen1.b:pen2:drawmode:pad End NEWTYPE FindScreen 0 *f.fontinfo=ASLFontRequest(15) If *f NPrint *f\name NPrint *f\ysize NPrint *f\pen1 NPrint *f\pen2 NPrint *f\drawmode Else NPrint "cancelled" EndIf MouseWait Function: ASLScreenRequest -------------------------------------------------------------------------- Syntax: ASLScreenRequest (enable_flags) Those who are just getting to grips with 2.0 and above will find this command makes your programs look really good, however I haven't got time to explain the difficulties of developing programs that work in all screen resolutions (what are ya?). EXAMPLE: #width=1:#height=2:#depth=4:#overscan=8:#scroll=16 NEWTYPE .screeninfo id.l width.l height.l depth.w overscan.w autoscroll.w bmapwidth.l bmapheight.l End NEWTYPE FindScreen 0 *sc.screeninfo=ASLScreenRequest(31) If *sc NPrint *sc\width," ",*sc\height," ",*sc\depth Else NPrint "cancelled" EndIf MouseWait The New GadTools Library (#mygadtoolslib=141) GadTools is a 2.0 and greater extension to the operating system that gives the Amiga programmer a few extra enhancements to create juicy user interfaces with. Instead of listing each as a separate command this issue I'll just add a brief description and a relevant taglist to each of the 12 gadgets. The Commands: ATTACHGTLIST GTBEVELBOX GTTAGS GTCHANGELIST GTGADPTR GTSETATTRS You are allowed both standard gadgets and GadTools ones in the same window, of course id clashes must be avoided and unlike standard gadgets, gadtools gadgets are attached to the Window after it is open with the AttachGTList command. GTButton GTList#,id,x,y,w,h,Text$,flags Same as Blitz2's TextGadget but with the added flexibility of placing the label Text$ above, below to the left or right of the button (see flags). GTCheckBox GTList#,id,x,y,w,h,Text$,flags A box with a check mark that toggles on and off, best used for options that are either enabled or disabled. GTCycle GTList#,id,x,y,w,h,Text$,flags,Options$ Used for offering the user a range of options, the options string should be a list of options separated by the | character eg. "HIRES } LORES } SUPERHIRES" GTInteger GTList#,id,x,y,w,h,Text$,flags,default A string gadget that allows only numbers to be entered by the user. GTListView GTList#,id,x,y,w,h,Text$,flags,list() The ListView gadget enaables the user to scroll through a list of options. These options must be contained in a string field of a Blitz2 linked list. Currently this string field must be the second field, the first being a word type. GTMX GTList#,id,x,y,w,h,Text$,flags,Options$ GTMX is an exclusive selection gadget , the Options$ is the same as GTCycle in format, GadTools then displays all the options in a vertical list each with a hi-light beside them. GTNumber GTList#,id,x,y,w,h,Text$,flags,value This is a readonly gadget (user cannot interact with it) used to display numbers. GTPalette GTList#,id,x,y,w,h,Text$,flags,depth Creates a number of coloured boxes relating to a colour palette, GTScroller GTList#,id,x,y,w,h,Text$,flags,Visible,Total A prop type gadget for the user to control an amount or level, is accompanied by a set of arrow gadgets. GTSlider GTList#,id,x,y,w,h,Text$,flags,Min,Max Same as Scroller but for controlling the position of display inside a larger view. GTString GTList#,id,x,y,w,h,Text$,flags,MaxChars A standard string type gadget GTText GTList#,id,x,y,w,h,Text$,flags,Display$ A read only gadget (see GTNumber) for displaying text messages. The parameters x,y,w,h refer to the gadgets position and size, the Text$ is the label as referred to above. The flags field is made up of the following fields: #_LEFT=1 ;positioning of the optional gadget label Text$ #_RIGHT=2 #_ABOVE=4 #_BELOW=8 #_IN=$10 #_High=$20 ;highlight #_Disable=$40 ;turned off #_Immediate=$80 ;activate on gadgetdown #_BoolValue=$100 ;checkbox on #_Scaled=$200 ;scale arrows for slider #_Vertical=$400 ;make slider/scroller vertical Statement: AttachGTList -------------------------------------------------------------------------- Syntax: AttachGTList GTList#,Window# The AttchGTList command is used to attach a set of GadTools gadgets to a Window after it has been opened. Statement: GTTags -------------------------------------------------------------------------- Syntax: GTTags Tag,Value [,Tag,Value...] The GTTags command can be used prior to initialisation of any of the 12 gadtools gadgets to preset any relevant Tag fields. The following are some useful Tags that can be used with GTTags: #tag=$80080000 #GTCB_Checked=#tag+4 ; State of checkbox #GTLV_Top=#tag+5 ; Top visible item in listview #GTLV_ReadOnly=#tag+7 ; Set TRUE if listview is to be ReadOnly #GTMX_Active=#tag+10 ; Active one in mx gadget #GTTX_Text=#tag+11 ; Text to display #GTNM_Number=#tag+13 ; Number to display #GTCY_Active=#tag+15 ; The active one in the cycle gad #GTPA_Color=#tag+17 ; Palette color #GTPA_ColorOffset=#tag+18 ; First color to use in palette #GTSC_Top=#tag+21 ; Top visible in scroller #GTSC_Total=#tag+22 ; Total in scroller area #GTSC_Visible=#tag+23 ; Number visible in scroller #GTSL_Level=#tag+40 ; Slider level #GTSL_MaxLevelLen=#tag+41 ; Max length of printed level #GTSL_LevelFormat=#tag+42 ;* Format string for level #GTSL_LevelPlace=#tag+43 ;* Where level should be placed #GTLV_Selected=#tag+54 ; Set ordinal number of selected #GTMX_Spacing=#tag+61 ;* Added to font height to All of the above except for those marked * can be set after initialisation of the Gadget using the GTSetAttrs command. The following is an example of creating a slider gadget with a numeric display: f$="%2ld" : GTTags #GTSLLevelFormat, &f$, #GTSLMaxLevelLen, 4 GTSlider 2,10,320,120,200,20,"GTSLIDER",2,0,10 Function: GTGadPtr -------------------------------------------------------------------------- Syntax: GTGadPtr (GTList#,id) GTGadPtr returns the actual location of the specified GadTools gadget in memory. Statement: GTBevelBox -------------------------------------------------------------------------- Syntax: GTBevelBox GTList#,x,y,w,h,flags GTBevelBox is the GadTools library equivalent of the Borders command and can be used to render frames and boxes in the currently used Window. Statement: GTChangeList --------------------------------------------------------------------------- Syntax: GTChangeList GTList#,id [ ,List() ] GTChangeList must be used whenever a List attached to a GTListView needs to be modified. Call GTChangeList without the List() parameter to free the List, modify it then reattache it with another call to GTChangeList this time using the List() parameter. Statement: GTSetAttrs -------------------------------------------------------------------------- Syntax: GTSetAttrs GTList#,id [,Tag,Value...] GTSetAttrs can be used to modify the status of certain GadTools gadgets with the relevant Tags. See GTTags for more information on the use of Tags with the GadTools library. PRINTER LIBRARY This is a library for using the printer.device!!! There are only four commands included, but I think these are the most wanted ones... The Commands: CHECKPRT PRTCOMMAND PRTTEXT HARDCOPY Statement: CheckPrt -------------------------------------------------------------------------- Syntax: status.b=CheckPrt Modes : AMIGA/BLITZ Description: Checks the state of the Printer and return it. status: -1 = Printer Off -3 = Printer Offline -4 = Printer On Bugs: I had exculded this Routine, because it doesn' t worked 100%...I have now reincluded it and compiled with the newest version of the BB2 compiler...It seems that it now works 100%... Statement: PrtCommand -------------------------------------------------------------------------- Syntax: PrtCommand Command,Para1,Para2,Para3,Para4 Modes : AMIGA Description: Send a ESC-Sequence to the printer. Command: Escape-Sequence Para1 - Para 4: Parameters for ESC-Sequence Beispiel: PrtCommand 6,0,0,0,0 ;Kursiv on PrtCommand 7,0,0,0,0 ;Kursiv off End Of Part Two