SCASM 2.88

basic and universal commands

  
command index:
 
back to main index
 
Header( )
LatRange( )
Area( )
EndA
RefPoint( )
SetScale( ) / ReScale( )
SuperScale( ) / SetScaleX( )
Nop
defining data ...

Every scenery you are creating with this programm has to start with the Header command followed by the LatRange command. These two commands are initialising the minimum file header for further actions. These two commands can only be omitted if you want to create a RAW output file.

 
 

This command MUST be the first in your main scenery input file. It generates the BGL-file header which defines the boundaries of the area covered by your scenery file.
The Header is not needed for RAW BGL output files -> Area( R ).

Lat/Lon  values in the format DD:MM:SS.SSSS
If the optional * character is entered the correct order of RightLon and LeftLon is not tested. You will need this option only if your scenery is crossing the date line (180th meridian). Normaly not used!
type 
1...4  this number has something to do with your FS5 *.VIS files.
The following numbers are associated with:
visual scenery (sect 9),
synth blocks (sect 1..6)
FS98 AFD-BGL's
FS5.0 crop duster world, do not use it.
navaids as VOR, ILS, NDB, Markers
airport menu (FS5 style), ATIS
 

It seems these numbers shows FS5 how important the information in this file is and how often to scan this file for scenery updating. So you should put all visible things into type 1 and less important things such as menu and land-me data into type 4 files. But if you are only designing a small scenery you can put all into one file.


TOP 

FS5 - FS2002
LatRange( BottomLat TopLat )
 

This command has to follow the Header command. The FS5 scenery is organised in latitude bands and this instruction defines one of them. There can be several latitude bands in one scenery file (.BGL file) but SCASM can only handle one of it per source file. If your scenery covers a large north to south distance, lets say more than 2 to 3 degrees you have to use different source files for each latitude band.
You then have the option to combine the resulting .BGL files with the help of SCLINK.
The LatRange instruction is used for all BGL-sections except for
ground tiles (Seed's/sections 1 to 6),
BGL libraries,
RAW output,
Section 19 data (Exclude & Exception) and
new facility BGL's (section 20).


TOP 

The following commands are for building the visual scenery. Traditionally these are called section 9 commands. All visual scenery commands are grouped into Area() blocks.

FS5 - FS2002
Area( type Lat Lon Rng )
 

This marks the begin of an block of visual scenery commands.

There are different types of area blocks with different properties. When I started the SCASM project I simply chose the first byte of the hex code as a name for them.
The visibility ranges are different for each type. I do not know the absolute limits. I have different values from different sources for them. It seems there are also differences in different FS versions.

type 
0...22 km (0...40 km)
40...130 km (invisible 0...40 km)
0...255 km (0...130 km)
Used mainly for calling lib objects in CFS1 and FS2000+ sceneries. It is reported that this type gives better frame rates than type 5. This type can only contain 255 bytes of BGL data.
This area type seem to be a very special one. It is used to define a library of bitmaped tiles in CFS1. This type can contain more than 64kb of data and has a very large visibility range. The disadvantage is that only one Area( E .. ) type per active scenery can be used.
This Area type maybe discontinued in versions later than FS2002.
In FS2000 there are some new Area types available. The purpose of these types is unknown.
maximum code length 245 bytes (some designers use it for lib objects with good results).
maximum code length 245 bytes
no size limit
You can use several of these types in one scenery.
no size limit
no size limit
special SCASM option, see Area(R)

I obseved the range can be influenced by the scaling factor and the V# parameters of the RefPoint() command.
Lat/Lon  location of this area
Rng  range in km units (integer ).
It seems this value controls how long this area needs to be hold in the scenery buffer. This does not automatically mean that the objects in this Area() are displayed, since the visibility is also controled by the V# parameters in the reference points (within this Rng limit). Since it is told FS5.1 can only hold about 256 k bytes of scenery, you should not use unrealistic large values to avoid wasting memory.

Note! In FS5 a single scenery area is limited to 16kB. SCASM 1.6g/1.67 (and above) is testing this limit and will produce an error message, but the scenery is compiled correctly up to about 24..32 Kb (depending on the current buffer status).
FS98 is able to handle larger objects. Use SCASM's SET() command to enable larger object compilation.
It is reported that FS2000 does not show the maximum visibility range.


TOP 

FS5 - FS2002
EndA
 

End_of_Area
This marks the end of an Area block. No code is generated. You can see this command as a special jump destination. All unresolved Jump()s and all 'empty' labels (-> only ':') are directed to this location.
This command also causes some internal actions such as patching all label references and writing buffers to disk.


TOP 

FS5 - FS2002
Area( R )
 

This is an option to produce a raw BGL output of visual scenery objects, which is usefull if you want to process the compiled BGL code with other programms.
To enable the RAW output you also have to set the RAW flag by inserting the line "Set( RAW 1 )" to your source text. This suppresses the output of the normal BGL file header. If you get an buffer overflow you have also to increase the working buffer by using Set( BUF ### ).
No Header() and LatRange() commands are needed for an RAW-output source file. The RAW output file cannot be used directly in FS and also SCLINK cannot handle it. The output file starts with a long integer number (4 bytes) which indicates how many valid bytes of BGL data will follow.
SCASM can only compile one "raw" object per compile run. A typical source file for raw output will look like:

Set( RAW 1 )
Set( BUF 200 ) ; for 200KB buffer size
Area( R )
    ...
    ... ; your BGL instructions
    ...
EndA

TOP 

FS5 - FS2002
RefPoint( type :Label scale Lat Lon [...] )
 

This command defines a reference point for further actions. All distances entered now are relative to this point. If FS5 decides the viewer is too far away, a jump to :Label is performed and the following commands are not executed. For the Refpoint type selector I simply chose the first digit of the generated hex code.
The optional v1= and v2= parameters may help the drawing systen to speed up things in dense sceneries. They are used to control the visibility of objects.

type  type of the RefPoint. There are different types of RefPoints as follows:
abs 
2
absolute referencepoint, MSL (main sea level)
This type is used if an absolute elevation setting is needed. The elevation is set with the "E=" parameter. The scenery object is put on this level, regardless what the altitude definition in the coresponding synth tile says.
rel 
7
relative referencepoint, always 0 AGL
The altitude is adjusted to the same level as defined in the Synth Tile block you are standing on. The "E=" parameter is ignored.
ns 
3
Reference point with NO SCALE setting. This type is often used for very detailed complex static objects. The altitude setting for this referencepoint type is always absolute (=MSL). For setting the scale factor use the SuperScale() or SetScaleX() command.

:Label  symbolic name of a jump destination
scale  scale factor, if scale = 1 all distances are in meters. Floating point values accepted. This parameter is not allowed for type "ns".
Lat/Lon  Position
 
These optional parameters are prefixed by an identifier
E= ###  elevation of this point in meters (MSL)
v1= ##  visibility range of this object in meters (int)
v2= ##  radius of this object in design units (int). This is in meters if scale factor is 1.

Note: according to the FS2K scenery SDK v1 (range) and v2 (size) should not left blanc because this will result in a slow running scenery.


TOP 

FS5 - FS2002
RefPoint( nsi :Label varptr [...] )
 

Referencepoint with no scale and with indirect position via varptr. (v1= ##; v2= ##; optional) For scaling use SuperScale(). Used for moving objects.


TOP 

FS5 - FS2002
RefPoint( ind :Label scale var [...] )
 

This reference point is used in the aircraft model files and uses an indirect position definition.

ind  the keyword IND indicates that indirect positioning is used.
var  the address of the variable area that holds the current position (Lat, Lon, Alt).
[...]  v1= ##, v2= ##, optional

TOP 

FS5 - FS2002
ShadowPosInd( var )
 

(SHADOWVPOSITION in FS98SDK)
This command sets the shadow position of an non static object like an aircraft. Since the position is variable in this case it is addressed indirect by a pointer to an array of variables. Used in .MDL files and dynamic object libraries.


TOP 

FS5 - FS2002 ?
ShadowPos( Lat Lon ALt )
 

This command sets the position for a shadow of an static object which is not on the ground like the blimp in thc Chicago scenery.
ShadowPos(...)
SuperScale(...)
ShadowCall(...)


TOP 

FS5 - FS2000 ?
SetScale( :Label V1 V2 scale )
ReScale( :Label V1 V2 scale )
 

This command sets/changes the scale factor for normal reference points (abs, rel). If the visual range test parameters are used, a range test is done.

V1, V2  visual range test parameters (used if not 0). Same as in the reference points.
:Label  jump to this label if range test is negative.
scale  scale factor (decimal, floating point value)

TOP 

FS5 - FS2002
SuperScale( :Label v1 v2 sx )
SetScaleX( :Label v1 v2 sx )
 

Sets a sort of binary scale factor for reference points types ns and ShadowPos().

Maybe this sort of scaling speeds up the internal calculations because the scaling can now be done by bit shifting. Do not confuse with 2*10^sx . Note: Some users reported problems with this instruction when used in library objects, such as static aircrafts, converted from MDL files.

V1, V2  visual range test parameters (used if not 0). Same as in the reference points.
:Label  jump to this label if range test is negative.
SX  This is actualy the exponent of the scale factor (integer). True scale factor is calculated as follows:
scale = ( 2^SX ) / 65536
example:
scale = ( 2^16 ) / 65536 = 1
As a result the scale factor can only be set to a value which can be expressed as a power of 2 (devided by 65536).
Another way to calculate scale is:
scale = 1 / 2^(16-sx)
with sx = 7 this results in:
scale = 1 / 2^(16-7)
scale = 1 / 2^9
scale = 1 / 512

Normally only values up to 31 are allowed. Values of 32 and obove are interpreted as a local variable which carry the scaling information in the normal fractional format.


TOP 

FS5 - FS2002
Nop
 

No Operation. This command does nothing. It only occupies 2 bytes of BGL code. Usefull for patch programms or to make space for later patches. Same as Dwx( 0x02 ).


TOP 

 

The following commands inserts any data value in the visual scenery area. They are included to give experts a tool for trying new scenery commands. More than one value per instruction is possible. The internal instruction counter variable $IC always points the relative address of the first value.

ALL
Dlx( hhhhhhhh )
 

DefineLongHex. A 32 bit hex value is inserted.


TOP 

ALL
Dld( dddddddd )
 

DefineLongDecimal. A decimal value is converted in 32 bit hex format and inserted.


TOP 

ALL
Dwx( hhhh .. hhhh )
 

DefineWordHex. All hex values in the brackets are copied into the file.


TOP 

ALL
Dwd( ddddd .. ddddd )
 

DefineWordDecimal. All decimal values in the brackets are copied into the file.


TOP 

ALL
Dbx( hh .. hh )
 

DefineByteHex.


TOP 

ALL
Dbd( dd .. dd )
 

DefineByteDecimal


TOP 

ALL
Dba( AbCdE )
 

DefineByteASCII


TOP 

FS2000 - FS2002
Dr4( f_val )
 

This command defines a 4 bytes REAL4 value (IEEE format) from an floating point input number.
This command is used to build up data tables which some of the new FS2000 instructions in MDL files needs.


 

    
TOP © Manfred Moldenhauer