Library Objects

The library system is a powerful feature of BGL; the library system enables code in one BGL file to call code in another BGL file. Using the library system, you can set up libraries of objects that can be called at different positions and scales from any BGL file. The following example shows a simple runway defined as a library object

;DATABASE HEADER ********************************************************
dw0001;00 world set number (not saved to file list)
dd0004c4eabh;02 N bound 43 degrees meter units
dd000400000h;06 S bound
dd0cf000000h;10 E bound 85 degrees 32-bit pseudo
dd0bf000000h;14 W bound
dd0;18 VOR_DATA
dw0;22 lowest vor freq (channel 0–199)
dw0;24 highest vor freq (108.00–117.95)
dd0;26 seeds level 8
ddSYNTH_SEEDS_09;30 seeds level 9
dd0;34 seeds level 10
dd0;38 seeds level 11
dd0;42 seeds level 12
ddSYNTH_SEEDS_13;46 seeds level 13
dd0;50 seeds level 14
dd0;54 seeds level 15
dd0;58 OBJECT_DATA
ddLIBRARY_DATA;62 LIBRARY_DATA
dd0;66 FACILITIES_DATA
dd0;70 ANCHOR POINT DATA
dd0;74 COM RADIO DATA
ddADF_DATA;78 ADF DATA
ddDYN_PATH_DATA;82 DYNAMIC OBJECT PATHS
dw3,3,2,1;86 Library id min (1233 in this case)
dw5,3,2,1;94 Library id max (1235 in this case)
LIBRARY_DATA:
rel_base=library_data
LIBRARY_OBJECT_PTR1,2,3,4,LITEM1
LIBRARY_EOL

LITEM1labelword
LIBRARY_OBJECT1,2,3,4,100,LITEM1_END
SCALEobject_end,0,0,S_16,0046fb1ah,0,0c1b3af36h,0,180,0 ;@meigs
half_lngth = 1130
half_width = 23
RESLIST0,4
VERTEXhalf_lngth,0,half_width
VERTEX-half_lngth,0,half_width
VERTEX-half_lngth,0,-half_width
VERTEXhalf_lngth,0,-half_width
SCOLORC_YELLOW
;runway 27
FACET40,32767,0,0,0,1,2,3
object_endlabelword
BGL_RETURN

LITEM1_ENDlabel word

The following example defines the library system specific entities that are used.

;LIBRARY DATABASE ********************************************************
;OpFormatDefinition
;-----------------------------------------------------------------
;;LIBRARY_OBJECT_PTR
;dd 0;00 32-bit rel_base relative ptr
;dw 0,0,0,0;04 64-bit ID (byte reversed)
;;LIBRARY_OBJECT
;dw 0,0,0,0;00 64-bit ID (byte reversed)
;db 0;08 image power
;dw 0;09 byte count
;db 0,0,0,0....;11 data (up to 65525-bytes)
LIBRARY_OBJECT_PTRmacroid1,id2,id3,id4,item
dditem-rel_base;;09 32-bit rel_base relative ptr
dwid4,id3,id2,id1;;01 64-bit ID (byte reversed)
endm

LIBRARY_EOLmacro
dd0
endm

LIBRARY_OBJECTmacroid1,id2,id3,id4,power,op_end
localop_base
op_basedwid4,id3,id2,id1;;00 64-bit ID (byte reversed)
dbpower;;08 image power
dwop_end-op_base;;09 byte count
;;11 data (up to 65525-bytes)
endm

Library objects are given unique 4-word identifiers called library IDs. The database header contains a pointer to the library data, and, at offsets 86 and 94, contains the minimum ID number and maximum ID number. The ID numbers are specified in byte-reversed order. It's important that you set these ID range limits so that when a library object is called, the BGL system can find the file it's located in. Use the BGL_LIBRARY command to call a library object, as shown in the following example.

BGL_LIBRARYmacroa,b,c,d
dw063h
dwd,c,b,a
endm

When you insert the BGL_LIBRARY command in BGL code, it's the same as using the BGL_CALL command, with one important difference. Instead of calling a BGL subroutine in the same file, BGL_LIBRARY calls the library object from whatever file it's located in. To project the runway in the preceding example, you would use the following command.

BGL_LIBRARY1,2,3,4

When a library object is called, the BGL system first searches its memory-resident libraries. If a library object with the same ID is found, it is called. If not, all available BGL files are searched. The search is quick and efficient because just the header of each file is read. If the ID that is called is out of the specified minimum/maximum range for that file, the next file is searched. When the object is found, it is put into its own memory area in the library.

If a library object is called and no object is found, the BGL system performs the equivalent of a BGL_RETURN; that is, it produces the same result as a null call. Although the size constraint in the macro is listed as 64K for each object, the real-world limit is 16K. However, if you need more space, you can use one BGL_LIBRARY object to call another BGL_LIBRARY object.