_MEM

From QB64 Phoenix Edition Wiki
Revision as of 22:44, 23 April 2026 by RhoSigma (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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


Syntax

DIM m AS _MEM


Description

Variable TYPE:

  • Memory DOT values are actually part of the built in memory variable type in QB64. The following TYPE is built in:
TYPE memory_type
  OFFSET AS _OFFSET       'start location of block(changes with byte position)
  SIZE AS _OFFSET         'size of block remaining at offset(changes with position)
  TYPE AS _OFFSET         'type description of variable used(never changes)
  ELEMENTSIZE AS _OFFSET  'byte size of values inside the block(never changes)
  IMAGE AS LONG           'the image handle used when _MEMIMAGE(handle) is used
  SOUND AS LONG           'the sound handle used when _MEMSOUND(handle) is used
END TYPE

The above TYPE is for clarification purposes only. It doesn't need to be pasted in
a program to use _MEM.

IMPORTANT NOTE: As of Build 20170802/57 onward (early v1.2 development), mem.TYPE has
been changed to be an _OFFSET, just as mem.SIZE and mem.ELEMENTSIZE.

Usage

  • 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 _OFFSET:


.TYPE values (version 1.000 and up incl. all QB64-PE releases)

  • [bit 0] 1* byte types (_BYTE)
  • [bit 1] 2* byte types (INTEGER)
  • [bit 2] 4* byte types (LONG or SINGLE)
  • [bit 3] 8* byte types (DOUBLE or _INTEGER64)
  • [bit 4] 16* byte types (reserved for future use)
  • [bit 5] 32* byte types (_FLOAT)
  • [bit 6] 64* byte types (reserved for future use)
  • [bit 7] 128 = integer types (_BYTE, INTEGER, LONG, _INTEGER64) (added to *)
  • [bit 8] 256 = floating point types (SINGLE, DOUBLE, _FLOAT) (added to *)
  • [bit 9] 512 = STRING types (fixed length or variable length)
  • [bit 10] 1024 = _UNSIGNED types (added to *+128)
  • [bit 11] 2048 = pixel data usually from _MEMIMAGE (added to 1+128+1024 for 256 color screens, or 2+128+1024 for text screens, or 4+128+1024 for 32-bit color screens)
  • [bit 12] 4096 = _MEM TYPE structure (NOT added to 32768)
  • [bit 13] 8192 = _OFFSET type (added to 4+128+[1024] or 8+128+[1024] or future_size+128+[1024])
  • [bit 14] 16384 = data created/defined by _MEMNEW(size) or _MEMNEW(offset,size)
  • [bit 15] 32768 = a custom, user defined type (ie. created with TYPE name ... END TYPE)
  • [bit 16] 65536 = an array of data (added to other type values defining the array's data type)

Note: If a future integer, float or other type doesn't have a size that is 1,2,4,8,16,32,64,128 or 256 it won't have a size-bit set.

Versions prior to 1.000 (never use with QB64-PE releases)

  • 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.


Examples

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 

'The $UNSTABLE command may not be necessary if HTTP integration has been fully accepted into QB64PE.
'Feel free to remark it out if the IDE flags the following line with an ERROR message.
'And kindly report the issue on our forums or Discord so that we can update this page to keep it as 100% relevant, as possible.

$UNSTABLE:HTTP

SCREEN _NEWIMAGE(500, 500, 32)

Image$ = Download$("https://qb64phoenix.com/qb64wiki/resources/assets/peWikiLogo.png", statusCode&) 'Let's try and download the QB64PE Logo from the web
IF statusCode& = 200 THEN '                                      200 says a proper connection was made to the web page in question
    i = _LOADIMAGE(Image$, 32, "memory") '                       and then we load it for use as a registered imange
ELSE
    PRINT "HTTP ERROR"; statusCode '                             can't get a proper connection to our webpage, so we don't have an image to work with.
    END '                                                        end and go report the issue on the forums, if you'd be so kind, dear user.
END IF

_PUTIMAGE (0, 0)-(500, 500), i '                                 put the image on the screen so we can view it
DIM m AS _MEM: m = _MEMIMAGE(i) '                                make a memblock and point it towards our image


'                                                           **** try uncommenting the following line and see what happens ****
'_MEMFREE m


IF m.TYPE AND 2048 THEN
    PRINT "this is/was an image"
    IF _MEMEXISTS(m) THEN '                                      check if memory m is still available
        PRINT t AND 7; "bytes per pixel"
        PRINT "image handle "; m.IMAGE
        PRINT "image width"; _WIDTH(m.IMAGE)
        PRINT "image height"; _HEIGHT(m.IMAGE)
    ELSE '                                                       if we removed the remark from the _MEMFREE above, we'll see the following message
        PRINT "Memory already freed!"
    END IF
END IF


' Content of the HTTP response is returned.
' The statusCode is also assigned.
FUNCTION Download$ (url AS STRING, statusCode AS LONG)
    DIM h AS LONG, content AS STRING, s AS STRING
    h = _OPENCLIENT("HTTP:" + url)

    statusCode = _STATUSCODE(h)

    WHILE NOT EOF(h)
        _LIMIT 60
        GET #h, , s
        content = content + s
    WEND
    CLOSE #h

    Download$ = content
END FUNCTION


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

SCREEN 13
PSET (0, 0), ASC("H") 'put the ASCII value of "H" into the top left corner of screen, which is the first byte of screen image memory
PSET (1, 0), ASC("E") 'put the ASCII value of "E" into the 2nd byte of screen image memory
PSET (2, 0), ASC("L") 'put the ASCII value of "L" into the 3nd byte of screen image memory
PSET (3, 0), ASC("L") 'put the ASCII value of "L" into the 4th byte of screen image memory
PSET (4, 0), ASC("O") 'put the ASCII value of "O" into the 5th byte of screen image memory                                                                                                                                                                                                            'put the ASCII value of "E" into the 2nd byte of screen image memory

DIM m AS _MEM '                         define m as a mem block
m = _MEMIMAGE(0) '                      point m to where our screen exists in memory

x1$ = _MEMGET(m, m.OFFSET, STRING * 5) 'm is the mem block that we're wanting to get information from
'                                       m.OFFSET is the mem block m starting position
'                                       STRING * 5 is the size and type of information that we want to get from that position in memory.

LOCATE 2, 1
PRINT LEN(x1$) '                        prints 5 bytes as we deliberately fetched STRING * 5 bytes with our _MEMGET above.
PRINT x1$ '                             prints the contents of that 5-byte string which we got above -- which is "HELLO" as CHR$() string character values
_MEMFREE m

 5
HELLO


Example 3: Using _MEM to convert _OFFSET to _INTEGER64. 

DIM x AS INTEGER
DIM m AS _MEM
m = _MEM(x)
PRINT m.OFFSET
PRINT ConvertOffset(m.OFFSET)


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
        DIM temp AS _INTEGER64 'On 64 bit OSes, an OFFSET is 8 bytes in size.
    $ELSE
        DIM temp AS LONG '      However, on 32 bit OSes, an OFFSET is only 4 bytes.
    $END IF
    _MEMGET m, m.OFFSET, temp 'Once we've sized our variable correctly, let's get it
    ConvertOffset&& = temp '   And then assign that long value to ConvertOffset&&
    _MEMFREE m '               Free the memblock
    $CHECKING:ON
END FUNCTION


Explanation: The above will print two numbers 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.


Example 4: Using _MEM with nested static arrays - basic form: 

Option _Explicit

Type TBox
    Values(0 To 3) As Integer
End Type

Dim Box(0 To 1) As TBox
Dim M As _MEM
Dim X As Integer

Box(1).Values(0) = 100
Box(1).Values(1) = 200
Box(1).Values(2) = 300
Box(1).Values(3) = 400

M = _Mem(Box(1).Values())

Print "SIZE        ="; M.SIZE
Print "ELEMENTSIZE ="; M.ELEMENTSIZE

X = _MemGet(M, M.OFFSET + M.ELEMENTSIZE * 2, Integer)
Print "Third element in array ="; X

_MemFree M
End

This example shows the simplest use of _MEM with a nested static array member. It creates a memory view for the nested array itself, then uses _MEMGET with .OFFSET and _MEM.ELEMENTSIZE to read one element.


Example 5: Using _MEM with nested static arrays - advanced form: 

$Console:Only
Dim As _MEM Parent, Kid1, Kid2, OneElement

Type UnsignedByte50
    U(49) As _Unsigned _Byte
End Type

Type A
    NestedA(49) As UnsignedByte50 '50 records, each containing 50 _UNSIGNED _BYTE elements
    NestedB(49) As String * 50
End Type

Dim Family(10) As A
Dim Text As Long, Value As _Unsigned _Byte

Parent = _Mem(Family())
Kid1 = _Mem(Family(0).NestedA())
Kid2 = _Mem(Family(0).NestedB())
OneElement = _Mem(Family(1).NestedA(0))

Family(0).NestedB(1) = "Qb64PE is beautiful" 'store text in the nested fixed-length string array

_MemCopy Kid2, Kid2.OFFSET, Kid2.SIZE To Kid1, Kid1.OFFSET 'copy the string data as raw bytes into NestedA

Do Until Text = Kid2.SIZE
    Value = _MemGet(Kid1, Kid1.OFFSET + Text, _Unsigned _Byte)
    If Value > 0 Then Print Chr$(Value);
    Text = Text + 1
Loop
Print
Print "Element size for Family(1).NestedA(0):"; OneElement.ELEMENTSIZE
Print "Nested ArrayA size:"; Kid1.SIZE
Print "Nested ArrayB size:"; Kid2.SIZE
Print "Array Family size:"; Parent.SIZE

_MemFree OneElement
_MemFree Kid2
_MemFree Kid1
_MemFree Parent

Note: Example 5 shows that _MEM can reference the parent array, a nested array member, or even a single element inside a nested array member. It also copies a text string from a nested fixed-length STRING array into a nested _UNSIGNED _BYTE record array and then reads it back as text.


See also


Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=MEM&oldid=10036"