QB64-PE/internal/help/BSAVE.txt

[[BSAVE]] saves the contents of an image array to a {{KW|BINARY}} file.


{{PageSyntax}}
::: '''BSAVE''' {{Parameter|savefile$}}''', [[VARPTR]]'''({{Parameter|Array(index)}})''',''' {{Parameter|Filesize&}}


{{Parameters}}
* ''savefile$'' is the STRING file name of the file designated to be created.
* ''Array(index)'' is the image [[arrays|array]] that already holds the [[GET (graphics statement)|GET]] image data.
* ''Filesize'' must be a bit over twice the size of the elements used in an {{KW|INTEGER}} [[Arrays|array]].


{{PageDescription}}
* To place image data into the array, use [[GET (graphics statement)|GET]] to store a box area image of the screen.
* [[SCREEN]] 12 can only GET 1/3 of the screen image at one time using a 26K array. 
* Image arrays are [[DIM]]ensioned as [[INTEGER]]. Use [[DEFINT]] when working with large graphic arrays.
* Any arrays can be saved, but Image arrays are most common.
* [[DEF SEG]] = [[VARSEG]] must be used to designate the array segment position in memory.
* [[VARPTR]] returns the Array index offset of the memory segment. Array sizes are limited to 32767 Integer elements due to the use of [[VARPTR]] in QB and '''QB64'''!.
* '''QB64''' can load larger arrays directly to and from binary files using [[PUT]] # and [[GET]] # without BSAVE. 
 * [[BSAVE]] files can later be opened with {{KW|BLOAD}}.


''Example 1:'' Saving array data to a file quickly.
{{CodeStart}} '' ''
 LB% = {{Cl|LBOUND}}(Array)
 bytes% = {{Cl|LEN}}(Array(LB%))
 filesize& = (({{Cl|UBOUND}}(Array) - LB%) + 1) * bytes% 
 {{Cl|DEF SEG}} = {{Cl|VARSEG}}(Array(0))
  {{Cl|BSAVE}} filename$, {{Cl|VARPTR}}(Array(LB%)), filesize&  ' changeable index
 {{Cl|DEF SEG}} '' ''
{{CodeEnd}}
: ''Explanation:'' Procedure determines the filesize from the array size automatically. {{KW|LBOUND}} is used with {{KW|UBOUND}} to determine array size and byte size. Works with any type of array except variable length Strings. Great for saving program data fast!



''Example 2:'' {{KW|BSAVE}}ing a bitmap and calculating the file size
{{CodeStart}} '' ''
 {{Cl|DEF SEG}} = {{Cl|VARSEG}}(Image(0))
 {{Cl|PSET}}(BMPHead.PWidth - 1, BMPHead.PDepth - 1)  'color lower right corner if black
 {{Cl|GET (graphics statement)|GET}} (0, 0)-(BMPHead.PWidth - 1, BMPHead.PDepth - 1), Image(NColors * 3) ' for 16 or 256 colors
 {{Cl|FOR...NEXT|FOR}} a& = 26000 {{Cl|TO}} 0 {{Cl|STEP}} -1
   {{Cl|IF...THEN|IF}} Image(a&) {{Cl|THEN}} ArraySize& = a&: {{Cl|EXIT FOR}}
 {{Cl|NEXT}}
 {{Cl|BSAVE}} SaveName$, {{Cl|VARPTR}}(Image(0)), (2 * ArraySize&) + 200 'file size
 {{Cl|DEF SEG}} '' ''
{{CodeEnd}}

: ''Explanation:'' The {{KW|FOR...NEXT|FOR}} loop reads backwards through the image array until it finds a value not 0. The {{KW|LONG}} {{Parameter|ArraySize&}} value is doubled and 200 is added. {{Parameter|BMPhead.PWidth}} and {{Parameter|BMPhead.PDepth}} are found by reading the bitmap's information header using a {{KW|TYPE}} definition. See [[Bitmaps]].


{{PageSeeAlso}}
* [[GET (graphics statement)]], [[PUT (graphics statement)]]
* [[BLOAD]], [[OPEN]], [[BINARY]]
* [[GET]], [[PUT]] {{text|(file statements)}}
* [[VARSEG]], [[VARPTR]]
* [[DEF SEG]], [[TYPE]]
* [[Text Using Graphics]]


{{PageNavigation}}