_MEM - mkilgore/QB64pe GitHub Wiki

The _MEM variable type can be used when working with memory blocks. It has no variable type suffix.

DIM m AS _MEM

Variable TYPE:

• Memory DOT values are actually part of the built in memory variable type in QB64. The following TYPE is built in:

<span style="color:red;">The above [[TYPE]] is for clarification purposes only. It '''doesn't need''' to be pasted in a program to use _MEM.</span>

<span style="color:red;">''IMPORTANT NOTE: As of Build 20170802/57 onward, mem.TYPE has been changed to be an _OFFSET, just as mem.SIZE and mem.ELEMENTSIZE.''</span>

• The _MEM type contains the following read-only elements where name is the _MEM variable name:

name.OFFSET is the current start position in the memory block AS _OFFSET. Add bytes to change position.

name.SIZE is the remaining size of the block at current position in bytes AS _OFFSET

name.TYPE is the type (represented as bits combined to form a value) AS LONG:

• 0 = UDT (user defined type) or memory created by _MEMNEW
• 1 = 1 bit ELEMENT.SIZE=1 *Only used along with specific types (currently integers or floats)
• 2 = 2 bit. ELEMENT.SIZE=2 *
• 4 = 4 bit. ELEMENT.SIZE=4 *
• 8 = 8 bit. ELEMENT.SIZE=8 *
• 16 = 16 bit. ELEMENT.SIZE=16 *
• 32 = 32 bit. ELEMENT.SIZE=32 *
• 64 = 64 bit. ELEMENT.SIZE=64 *
• 128 = 128 bit. ELEMENT.SIZE=128 *
• 256 = 256 bit. ELEMENT.SIZE=256 *
• 512(+ bit*) = integer types only(ie. whole numbers)
• 1024(+ bit*) = floating point types only(ie. numbers that can have a decimal point)
• 2048 = STRING type only
• 4096(+ 512 + bit*) = _UNSIGNED integer type only
• 8192 = _MEM type only
• 16384(+ 512 + bit*)= _OFFSET type only

• 1 = Integer types such as _BYTE, INTEGER, LONG, _INTEGER64 or _OFFSET
• 2 = _UNSIGNED variable types. Value must be added to the variable type value.(2 cannot be used by itself)
• 3 = ALL _UNSIGNED INTEGER type values.(add 1 + 2)
• 4 = Floating point types such as SINGLE, DOUBLE or _FLOAT
• 8 = STRING
• 0 = unknown(eg. created with _MEMNEW) or user-defined-types

• Note: _OFFSET values cannot be cast to other variable types reliably. _MEM is a reserved custom variable type.
• _MEM cannot reference variable length STRING variable values. String values must be designated as a fixed-length string.

Example 1: Demonstration of .IMAGE to determine an image's dimensions, .TYPE to verify the type and _MEMEXISTS to check image has not been freed

SCREEN _NEWIMAGE(500, 500, 32)
i = _LOADIMAGE("qb64_trans.png", 32)
_PUTIMAGE (0, 0), i
DIM m AS _MEM
m = _MEMIMAGE(i)
'try uncommenting the following line and see what happens
'_MEMFREE m
t = m.TYPE
IF...THEN t AND (boolean) 2048 THEN
  PRINT "this is/was an image"
  IF...THEN _MEMEXISTS(m) THEN 'check if memory m is still available
    PRINT t AND (boolean) 7; "bytes per pixel"
    PRINT "image handle "; m.IMAGE
    PRINT "image width"; _WIDTH (function)(m.IMAGE)
    PRINT "image height"; _HEIGHT(m.IMAGE)
  ELSE PRINT "Memory already freed!"
  END IF
END IF '' ''

Example 2: Converts the current destination SCREEN 13 image memory altered by PSET to a STRING value. SCREEN 13 only.

DIM m AS _MEM
m = _MEMIMAGE(0)  'copy the screen memory to m
x1$ = _MEMGET (function)(m, m.OFFSET, STRING * 5) 'get at block start position
LOCATE 2, 1:PRINT LEN(x1$) 'prints 5 bytes as size is STRING * 5
PRINT x1$ 'prints HELLO as ASCII character values
PRINT m.OFFSET; m.SIZE; m.ELEMENTSIZE
_MEMFREE m '' ''

 5
HELLO
 5448320  6400  1

Explanation: When a numerical _BYTE value is converted to a STRING, each byte is converted to an ASCII character. The QB64 IDE will capitalize _MEM dot values.

                                        m.SIZE = 320 * 200 = 6400 bytes
                                        m.ELEMENTSIZE = 1 byte

Example 3: Using _MEM to convert _OFFSET to _INTEGER64.

FUNCTION ConvertOffset&& (value AS _OFFSET)
$CHECKING:OFF
DIM m AS _MEM 'Define a memblock
m = _MEM(value) 'Point it to use value
$IF 64BIT THEN
    'On 64 bit OSes, an OFFSET is 8 bytes in size.  We can put it directly into an Integer64
    _MEMGET m, m.OFFSET, ConvertOffset&& 'Get the contents of the memblock and put the values there directly into ConvertOffset&&
$ELSE
    'However, on 32 bit OSes, an OFFSET is only 4 bytes.  We need to put it into a LONG variable first
    _MEMGET m, m.OFFSET, temp& 'Like this
    ConvertOffset&& = temp& 'And then assign that long value to ConvertOffset&&
$END IF
_MEMFREE m 'Free the memblock
$CHECKING:ON
END FUNCTION

Explanation: The above will print two numbers for us which should match. These numbers will vary, as they're representations of where X is stored in memory, and that position is going to vary every time the program is run. What it should illustrate, however, is a way to convert _OFFSET to _INTEGER64 values, which can sometimes be useful when trying to run calculations involving mem.SIZE, mem.TYPE, or mem.ELEMENTSIZE.

• _MEM (function)
• _MEMELEMENT, _MEMCOPY
• _MEMIMAGE, _MEMNEW
• _MEMGET, _MEMPUT
• _MEMFILL, _MEMFREE