Amiga Format CD 5

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

/ Amiga Format CD 5 / amigaformatcd05.iso / readerstuff / richard_thompson / cool_stars! / commands.doc < prev next >

Wrap

Text File | 1996-08-13 | 23.2 KB | 604 lines

Cool Stars V1.0 for AMOS Pro - Command Documentation ---------------------------------------------------- © July '96 Richard Thompson Okay, so when you've installed the extension, you'll be blessed with these 22 starfield commands... Cstars Reserve =Cstars Y Star Cstars Set =Cstars X Spd Cstars Set X Spd =Cstars Y Spd Cstars Set Y Spd =Cstars X Dir Cstars Set Colour =Cstars Y Dir Cstars X Rev =Cstars Colour Cstars Y Rev Cstars Clear Cstars Limit Cstars Draw Cstars Make Origins Cstars Bclear Cstars Origin Off Cstars Bdraw =Cstars X Star Cstars Calc Note that all commands start with 'Cstars' to avoid tokenization problems and to make Cool Stars! commands easy to identify in your programs. Now follows a detailed description of each command. I've also included possible error messages which the commands will produce if you enter invalid parameters... -------------------------------------------------------------------------- Instruction Name: Cstars Reserve Syntax: Cstars Reserve Cstars Reserve N,Multicol Function: Cstars Reserve reserves memory for N stars. Stars are reserved in fast memory if possible. You may have between 1 right up to 5000 stars in your starfield. Around 100-200 stars are usually more than enough for a nice looking display on a lowres 320*256 screen. Unlike other starfield extensions, Cool Stars! gives you the choice of either single coloured or -*MULTICOLOURED*- starfields! Multicol is simply a flag, set it if you want a multicoloured starfield. Single coloured stars are drawn onto only the 1st bitplane, so the colour of all the stars will normally be taken from colour register 1 (depending on the state of the other bitplanes). Multicoloured stars use the first TWO bitplanes so each star can be drawn in 1 of 4 colours. The colours are therefore taken from colour registers 0-3, although if other bitplanes are set, the stars may end up being drawn in a different colour. You can change the colours of the stars with AMOS Pro's Palette and Colour commands. Remember that multicoloured stars are only available in the registered version. If you attempt to reserve multicoloured stars in the shareware version, you'll get an error message. :-) It's very important to realise that you must call Cstars Reserve when the screen where you intend to display the stars on is the current screen. This is because Cstars Reserve precalculates tables of data from the current screen which gives extra speed when you get round to displaying the stars. When you call one of the star clearing or star drawing commands, Cool Stars! takes data out of these tables to quickly draw the stars onto the screen you reserved them on. -*NEVER*- resize, reopen or close the screen between reserving the stars with Cstars Reserve and clearing and drawing the stars. This is because the precalculated data may no longer be valid for the screen and anything could happen. A Cool Stars! starfield can only be displayed on one screen at any one time. If you have used a starfield on one screen and then at some other point in a program you wish to display a starfield on a different screen, simply make the screen you want to display it onto the current screen (using Screen) then call Cstars Reserve N,Multicol again to re-reserve the stars. The starfield commands work fine with Double Buffering when Autoback 0 mode is used. If you intend to display your starfield on a double buffered screen (which you probably will), you must Double Buffer your screen -*BEFORE*- calling Cstars Reserve, if not, the star clearing and drawing commands will get confused. You can call Cstars Reserve with no parameters to free the starfield. All memory used by the stars will be released back to the system. When you've freed a starfield it can no longer be used. Normally, you don't have to worry at all about freeing starfields, since Cool Stars! does this automatically when you run a program, do a Default or leave AMOS Pro. Possible Errors: SCREEN NOT OPENED ILLEGAL FUNCTION CALL - If N<1 or N>5000. MULTICOLOURED STARS ARE ONLY AVAILABLE IN THE REGISTERED VERSION! - If you attempt to reserve multicoloured stars in the shareware version. SCREEN MUST HAVE AT LEAST 4 COLOURS! - If you attempt to reserve multicoloured stars on a 2 colour screen. -------------------------------------------------------------------------- Instruction Name: Cstars Set Syntax: Cstars Set N,X,Y Cstars Set N,X,Y,X Spd,Y Spd Cstars Set N,X,Y,X Spd,Y Spd,Col Function: Cstars Set allows you to set the coordinates, speed (including direction) and colour for an individual star. There are 3 versions of this command. The first enables just the coordinates to be set. The second version enables the coordinates and speed (including direction) to be set. The third version is the same as the second except the colour of the star is also set. N is simply the number of the star. X,Y are the screen coordinates of the star. X Spd and Y Spd denote the speed and direction of the star. When you update your stars with Cstars Calc, X Spd is added to the X coordinate and Y Spd is added to the Y coordinate. Using negative X Spd values will make stars fly to the left, positive values will make them fly to the right. Likewise, using negative Y Spd values will make stars fly upwards, positive values will make them fly downwards. If both X Spd and Y Spd are set to 0, the star coordinates won't change when you call Cstars Calc. The colour parameter is only useful for multicoloured stars. You should specify a value from 0-3, representing a colour register. If you attempt to specify this parameter with a single coloured starfield, it will simply be ignored. Note that as yet, it isn't possible to omit parameters from this command. eg. Cstars Set 1,,Y to just change the y coordinate doesn't work. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars X Spd Syntax: Cstars X Spd N,X Spd Function: Cstars X Spd allows you to quickly set just the x speed for an individual star. N is the number of the star, X Spd denotes the speed. Negative X Spd values will make the star fly to the left when Cstars Calc is called. Positive X Spd vales will make the star fly to the right when Cstars Calc is called. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars Y Spd Syntax: Cstars Y Spd N,Y Spd Function: Cstars Y Spd allows you to quickly set just the y speed for an individual star. N is the number of the star, Y Spd denotes the speed. Negative Y Spd values will make the star fly upwards when Cstars Calc is called. Positive Y Spd vales will make the star fly downwards when Cstars Calc is called. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars Colour Syntax: Cstars Colour N,Col Function: This command is only useful for multicoloured stars. If you attempt to use this command with a single coloured starfield, nothing will happen. Cstars Colour allows you to quickly set the colour of an individual star. N is the number of the star, Col is a colour from 0-3 which represents a colour register. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars X Rev Syntax: Cstars X Rev Cstars X Rev N Cstars X Rev N1 To N2 Function: Cstars X Rev allows you to reverse the x direction which stars are travelling in. Cstars X Rev achieves this by quickly toggling the sign of X Spd for the star(s) specified. There are 3 versions of the command. The first reverses the x direction of ALL stars in the starfield. The second version reverses the x direction for just star N. The third version reverses the x direction for stars N1 to N2 inclusive. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved or N1<1 or N1>Number of stars reserved or N2<N1 or N2>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars Y Rev Syntax: Cstars Y Rev Cstars Y Rev N Cstars Y Rev N1 To N2 Function: Cstars Y Rev allows you to reverse the y direction which stars are travelling in. Cstars Y Rev achieves this by quickly toggling the sign of Y Spd for the star(s) specified. There are 3 versions of the command. The first reverses the y direction of ALL stars in the starfield. The second version reverses the y direction for just star N. The third version reverses the y direction for stars N1 to N2 inclusive. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved or N1<1 or N1>Number of stars reserved or N2<N1 or N2>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars Limit Syntax: Cstars Limit Cstars Limit X1,Y1 to X2,Y2 Function: Normally, Cool Stars! will allow your stars to fly around the entire screen. However, there may be times in your programs when you want to limit your starfield to just a rectangular area of the screen. This is what Cstars Limit does. X1,Y1 To X2,Y2 describes the area where your starfield will be confined to. Cool Stars! will then ensure that all stars stay confined to this area at all times. Calling Cstars Limit with no parameters will confine the stars to the entire screen again. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If X1<0 or X1>=Screen Width or X2<X1 or X2>=Screen Width or Y1<0 or Y1>=Screen Height or Y2<Y1 or Y2>=Screen Height. -------------------------------------------------------------------------- Instruction Name: Cstars Make Origins Syntax: Cstars Make Origins Function: This is one of Cool Stars! most interesting commands which is unique to Cool Stars!. It enables you to create special effects which simply couldn't be done with other starfield extensions. The origin mode enables you to change the behaviour of your stars. Normally, when a star flies off of the edge of the screen, it "wraps around" and reappears on the opposite edge of the screen. This is when origin mode is -*OFF*-. In origin mode, each star has it's own origin. Each star will fly from this origin to the edge of the screen. When it's reached the edge of the screen, rather than wrapping around to the opposite edge of the screen, the star reappears at it's origin. Okay, but what use is this? A good application of this command is to make stars fly from the centre of the screen towards the edge of the screen. Useful in your mega demo/game or what ever when you can have your credits scrolling over stars which appear to be "shooting out of the screen", as opposed to simply flying from one edge to the opposite edge of the screen. When you call Cstars Make Origins, origin mode is automatically turned on. Cstars Make Origins looks at the position of every single star and makes a note of it's position - this is it's origin. Whenever a star passes off of the edge of the screen, the star will reappear at it's origin. So to clarify things, let's take the example of getting stars to fly from the centre of the screen - this is what you'd need to do... 1) First reserve your stars with Cstars Reserve. 2) Position your stars at random around the centre of the screen (use Cstars Set). 3) Call Cstars Make Origins - Cool Stars! will look at the position of each star in turn and makes a note of it's current coordinates. These coordinates are the origin of the star. 4) Now when ever you use Cstars Calc and a star flies off of the edge of the screen, each star will return back to it's origin - it's that simple! Of course, since each star has it's own origin you could have some stars flying from one area of the screen, some other stars flying from another area of the screen etc. Take a look at the examples programs included in this distribution. Possible Errors: STARS NOT RESERVED -------------------------------------------------------------------------- Instruction Name: Cstars Origin Off Syntax: Cstars Origin Off Function: This command turns the origin mode off. Now when a star reaches the edge of the screen it "wraps around" and reappears on the opposite edge of the screen instead of returning to it's origin. Possible Errors: None -------------------------------------------------------------------------- Function Name: Cstars X Star Syntax: X_Coordinate=Cstars X Star(N) Function: Cstars X Star is a simple function which returns the x coordinate of an individual star. N is the number of the star. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Function Name: Cstars Y Star Syntax: Y_Coordinate=Cstars Y Star(N) Function: Cstars Y Star is a simple function which returns the y coordinate of an individual star. N is the number of the star. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Function Name: Cstars X Spd Syntax: X_Spd=Cstars X Spd(N) Function: Cstars X Spd is a simple function which returns the x speed of an individual star. N is the number of the star. The value returned may be negative or positive. The sign indicates direction. Negative values means the star will fly to the left, positive values mean the star will fly to the right. 0 indicates no movement on the x axis. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Function Name: Cstars Y Spd Syntax: Y_Spd=Cstars Y Spd(N) Function: Cstars Y Spd is a simple function which returns the y speed of an individual star. N is the number of the star. The value returned may be negative or positive. The sign indicates direction. Negative values means the star will fly upwards, positive values mean the star will fly downwards. 0 indicates no movement on the y axis. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Function Name: Cstars X Dir Syntax: X_Dir=Cstars X Dir(N) Function: Cstars X Dir is a simple function which returns the x direction of an individual star. N is the number of the star. This function returns 3 different values... -1 -> Star flying to the left. 0 -> No movement on x axis. 1 -> Star flying to the right. Note that X_Dir=Cstars X Dir(N) is the same as X_Dir=Sgn(Cstars X Spd(N)). Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Function Name: Cstars Y Dir Syntax: Y_Dir=Cstars Y Dir(N) Function: Cstars Y Dir is a simple function which returns the y direction of an individual star. N is the number of the star. This function returns 3 different values... -1 -> Star flying upwards. 0 -> No movement on y axis. 1 -> Star flying downwards. Note that Y_Dir=Cstars Y Dir(N) is the same as Y_Dir=Sgn(Cstars Y Spd(N)). Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Function Name: Cstars Colour Syntax: Colour=Cstars Colour(N) Function: Cstars Colour is a simple function which returns the colour of an individual star. N is the number of the star. In the case of multicoloured stars, this value will be from 0-3. If you call this function when using a single coloured starfield, this function always returns 1. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars Clear Syntax: Cstars Clear Function: Cstars Clear is a command to be used in conjunction with Cstars Draw. Cstars Clear is a fast version of AMOS Pro's Cls command, which only clears the bitplane(s) the stars are drawn. This command utilises the blitter. Cstars Clear is an intelligent command. If your using single coloured stars, Cstars Clear will automatically clear just the first bitplane. If your using multicoloured stars, Cstars Clear will automatically clear the first two bitplanes. Note that Cstars Clear will always clear the -*ENTIRE*- bitplane(s), even if you have limited your starfield to a rectangular area of the screen with Cstars Limit. Therefore, the smaller the size of the screen, the faster the command will be. Since if you use the Cstars Clear and Cstars Draw commands to clear and draw your stars, the first (and second if using multicoloured stars) bitplane(s) gets corrupted. These commands would therefore be useless if you wanted to pass your stars over a graphic (maybe a logo, a scrolltext or whatever). Instead, you can use the Cstars Bclear and Cstars Bdraw commands instead to clear and draw stars in these circumstances. Possible Errors: STARS NOT RESERVED -------------------------------------------------------------------------- Instruction Name: Cstars Draw Syntax: Cstars Draw Cstars Draw N Cstars Draw N1 To N2 Function: Cstars Draw is a command to be used in conjunction with Cstars Clear and is used to actually draw the stars onto the screen. There are 3 different different versions of this command. This first draws ALL stars in the starfield. The second version only draws star N. The third version will draw stars N1 To N2 inclusive. Cstars Draw will draw either single coloured or multicoloured starfields, depending on the type of starfield you reserved with Cstars Reserve. This command is lightening fast, which uses the main processor. Even with a standard MC68000 processor, the command can plot around 500 single coloured stars per vbl. Users with faster processors will be able to display many more per vbl. Multicoloured stars take slightly longer to draw, since 2 bitplanes are involved giving the processor more work to do. However, they are still relatively fast and you can still get a nice multicoloured starfield moving at 50 frames per second, even with a MC68000 processor!! Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved or N1<1 or N1>Number of stars reserved or N2<N1 or N2>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars Bclear Syntax: Cstars Bclear Function: Cstars Bclear is a command to be used in conjunction with Cstars Bdraw. These commands are an alternative to Cstars Clear and Cstars Draw. Cstars Bclear is used to remove stars from the screen which have been drawn with Cstars Bdraw. However, unlike Cstars Clear which clears entire bitplane(s) totally corrupting graphics, Cstars Bclear will restore the background. This makes it possible to pass stars over graphics such as logos, scrolltexts etc. without corrupting the graphics. Possible Errors: STARS NOT RESERVED -------------------------------------------------------------------------- Instruction Name: Cstars Bdraw Syntax: Cstars Bdraw Cstars Bdraw N Cstars Bdraw N1 To N2 Function: Cstars Bdraw is a command to be used in conjunction with Cstars Bclear. These commands are an alternative to Cstars Clear and Cstars Draw. Cstars Bdraw is used to draw stars onto the screen. However, unlike Cstars Draw, Cstars Bdraw saves the background of each individual star before actually drawing it. This makes it possible to pass stars over graphics such as logos, scrolltexts etc. without corrupting the graphics. There are 3 different different versions of this command. The first version draws ALL stars in the starfield. The second version only draws star N. The third version will draw stars N1 To N2 inclusive. Cstars Bdraw will draw either single coloured or multicoloured starfields, depending on the type of starfields you reserved with Cstars Reserve. Cstars Bdraw uses the main processor, not the blitter. Users with faster processors will therefore be at an advantage. Cstars Bdraw is almost as fast as Cstars Draw but not quite, since Cstars Bdraw has to save the background of each star before drawing it. The processor therefore has slightly more work to do, so use Cstars Draw when possible. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved or N1<1 or N1>Number of stars reserved or N2<N1 or N2>Number of stars reserved. -------------------------------------------------------------------------- Instruction Name: Cstars Calc Syntax: Cstars Calc Cstars Calc N Cstars Calc N1 To N2 Function: Cstars Calc is called to calculate the new position of stars. Cstars Calc achieves this by adding the X Spd to the X coordinate and the Y Spd to the Y coordinate for each star. This command also checks to see if the star has passed off of the edge of the screen (or out of the LIMITED area if you've used Cstars Limit). If origin mode is off, the star will "wrap around" to the opposite edge of the screen. If origin mode is on, the star will be positioned back at it's origin. See Cstars Make Origins for details or Cool Stars! cool origin mode. There are 3 different versions of this command. The first version calculates the new coordinates for ALL stars in the starfield. The second version calculates the new coordinates for just star N. The third version calculates the new coordinates for stars N1 to N2 inclusive. Possible Errors: STARS NOT RESERVED ILLEGAL FUNCTION CALL - If N<1 or N>Number of stars reserved or N1<1 or N1>Number of stars reserved or N2<N1 or N2>Number of stars reserved. -------------------------------------------------------------------------- -*IMPORTANT*- - Concerns the star clearing and drawing commands! ---------------------------------------------------------------- Cstars Clear, Cstars Draw, Cstars Bclear and Cstars Bdraw will always use the bitplane(s) of the screen which you reserved your stars on, it doesn't matter at all which screen is the current screen when you call these commands. These 4 commands are highly optimised for speed. They use precalculated data which Cstars Reserve has created. You must therefore ensure that you haven't accidentally closed, resized or reopened the screen the stars were reserved on. If you have, the addresses may be invalid. These 4 commands may then end up changing some other parts of your Amiga's memory and a crash is very likely. Use these commands with care! Okay, that's the end of this doc file.