zbuff - c Memory Data Manipulation Library#

Adapted Air780E/Air700E Air780EP/Air780EPV Air601 Air101/Air103 Air105 ESP32C3 ESP32S3

Note

This page document is automatically generated by this file. If there is any error, please submit issue or help modify pr, thank you!

Tip

This library has its own demo,click this link to view zbuff’s demo example

Tip

There are also video tutorials in this library, click this link to view

Constant#

constant

type

explanation

zbuff.SEEK_SET

number

Based on head

zbuff.SEEK_CUR

number

Base on current position

zbuff.SEEK_END

number

Base Point at End

zbuff.HEAP_AUTO

number

automatic application (apply in psram if it exists, apply in sram if it does not exist or fails)

zbuff.HEAP_SRAM

number

Apply at SRAM

zbuff.HEAP_PSRAM

number

Apply in PSRAM

zbuff.create(length,data,type)#

Create zbuff

Parameters

Incoming Value Type

Explanation

int

Bytes

any

Optional parameter, filled with data for number and filled with string for string

number

Optional parameter, memory type, optional: zbuff.HEAP_SRAM (internal sram, default) zbuff.HEAP_PSRAM (external psram) zbuff.HEAP_AUTO (automatic application, application in psram if there is pram, application in sram if there is no pram or failure) Note: This item is related to hardware support

Return Value

return value type

explanation

object

zbuff object, which returns if the creation fails.nil

Examples

-- Create zbuff
local buff = zbuff.create(1024) -- Blank
local buff = zbuff.create(1024, 0x33) --Create a memory area with all initial values of 0x 33
local buff = zbuff.create(1024, "123321456654") -- Create and populate the contents of an existing string.

-- Create framebuff zbuff
-- zbuff.create({width,height,bit},data,type)
-- table Width, height, color position depth
@int optional parameters, populating data
@number Optional parameter, memory type, optional: zbuff.HEAP_SRAM (internal sram, default) zbuff.HEAP_PSRAM (external psram) zbuff.HEAP_AUTO (automatic application, application in psram if there is pram, application in sram if there is no pram or failure) Note: This item is related to hardware support
@return object zbuff object, which returns if the creation fails.nil
@usage
-- Create zbuff
local buff = zbuff.create({128,160,16})--Create a 128*160 framebuff
local buff = zbuff.create({128,160,16},0xf800)--Create a 128*160 framebuff with an initial state of red


buff:write(para,…)#

zbuff Write data (starting from the current pointer position; the pointer will move backward after execution)

Parameters

Incoming Value Type

Explanation

any

The data written to buff is one parameter when string is used and multiple parameters when number is used.

Return Value

return value type

explanation

number

Length of data successfully written

Examples

-- Read and write operations of class file
local len = buff:write("123") -- Write data, the pointer moves back accordingly to return the length of the written data.
local len = buff:write(0x1a,0x30,0x31,0x32,0x00,0x01)  -- Write multiple bytes of data by value

buff:read(length)#

zbuff Read data (starting from the current pointer position; the pointer will move backward after execution)

Parameters

Incoming Value Type

Explanation

int

Read the number of bytes in the buff

Return Value

return value type

explanation

string

Read Results

Examples

-- Read and write operations of class file
local str = buff:read(3)

buff:clear(num)#

zbuff Empty data (regardless of current pointer position; pointer position unchanged after execution)

Parameters

Incoming Value Type

Explanation

int

Optional, the default is 0. value to be set to, does not change the buff pointer position

Return Value

None

Examples

-- Initialize all 0
buff:clear(0)

buff:seek(base,offset)#

zbuff Set the cursor position (may be related to the current pointer position; the pointer will be set to the specified position after execution)

Parameters

Incoming Value Type

Explanation

int

Offset length

int

where, Base point, default zbuff.SEEK_SET. Zbuff. SEEK_SET: base point is 0 (start of file),zbuff.SEEK_CUR: base point is current position, zbuff.SEEK_END: base point is end of file

Return Value

return value type

explanation

int

Position of the cursor calculated from the beginning of the buff after setting the cursor

Examples

buff:seek(0) -- Set the cursor to the specified position
buff:seek(5,zbuff.SEEK_CUR)
buff:seek(-3,zbuff.SEEK_END)

buff:pack(format,val1, val2,…)#

Convert a series of data according to format characters and write (starting from the current pointer position; the pointer will move backward after execution)

Parameters

Incoming Value Type

Explanation

string

The format of the following data (see the following example for the meaning of symbols)

val

Incoming data, which can be multiple data

Return Value

return value type

explanation

int

Length of data successfully written

Examples

buff:pack(">IIHA", 0x1234, 0x4567, 0x12,"abcdefg") -- Write several data by format
-- A string
-- f float
-- d double
-- n Lua number
-- c char
-- b byte / unsignen char
-- h short
-- H unsigned short
-- i int
-- I unsigned int
-- l long
-- L unsigned long
-- < Small end
-- > big end
-- = Default Size End

buff:unpack(format)#

Read a series of data according to format characters (starting from the current pointer position; the pointer will move backward after execution)

Parameters

Incoming Value Type

Explanation

string

The format of the data (see the example of the pack interface above for the meaning of the symbol.)

Return Value

return value type

explanation

int

Length in bytes of data successfully read

any

Data read out by format

Examples

local cnt,a,b,c,s = buff:unpack(">IIHA10") -- Read several data by format
--If all are read successfully, cnt is 4+4+2+10=20

buff:read Type()#

Read data of a specified type (starting from the current pointer position; the pointer will move backward after execution)

Parameters

Incoming Value Type

Explanation

Comment

Read type can be:I8、U8、I16、U16、I32、U32、I64、U64、F32、F64

Return Value

return value type

explanation

number

Data read, if out of bounds nil

Examples

local data = buff:readI8()
local data = buff:readU32()

buff:write Type()#

Writes data of a specified type (starting from the current pointer position; the pointer will move backward after execution)

Parameters

Incoming Value Type

Explanation

number

Data to be written

Comment

Write type can be:I8、U8、I16、U16、I32、U32、I64、U64、F32、F64

Return Value

return value type

explanation

number

Length of successful write

Examples

local len = buff:writeI8(10)
local len = buff:writeU32(1024)

buff:toStr(offset,length)#

Take out the data according to the starting position and length (regardless of the current pointer position; the pointer position remains unchanged after execution)

Parameters

Incoming Value Type

Explanation

int

The starting position of the data (starting position is 0), and the default value is also 0

int

The length of the data. The default value is all data.

Return Value

return value type

explanation

string

Read out the data

Examples

local s = buff:toStr(0,5)--Read the first five bytes of data
local s = buff:toStr() -- Take out the entire zbuff data
local s = buff:toStr(0, buff:used()) -- Take out the used part, just like buff:query()

buff:len()#

Get the length of the zbuff object (regardless of the current pointer position; the pointer position remains unchanged after execution)

Parameters

None

Return Value

return value type

explanation

int

zbuff The length of the object

Examples

len = buff:len()
len = #buff

buff:setFrameBuffer(width,height,bit,color)#

Set the FrameBuffer property of the buff object (regardless of the current pointer position; the pointer position does not change after execution)

Parameters

Incoming Value Type

Explanation

int

FrameBuffer The width

int

FrameBuffer The height

int

FrameBuffer The color depth

int

FrameBuffer The initial color

Return Value

return value type

explanation

bool

Successful settings will return true

Examples

result = buff:setFrameBuffer(320,240,16,0xffff)

buff:pixel(x,y,color)#

Set or get the color of a FrameBuffer pixel (regardless of the current pointer position; The pointer position remains unchanged after execution)

Parameters

Incoming Value Type

Explanation

int

The distance from the leftmost, the range is 0 ~ width-1

int

Distance from the top, in the range of 0 ~ height-1

int

Color, if left blank to get the color of the location

Return Value

return value type

explanation

any

When the color is set, true will be returned if the color is set successfully; When the color is read, the value of the color is returned, and the value of the color is returned if the reading fails.nil

Examples

rerult = buff:pixel(0,3,0)
color = buff:pixel(0,3)

buff:drawLine(x1,y1,x2,y2,color)#

Draw a line (regardless of the current pointer position; the pointer position does not change after execution)

Parameters

Incoming Value Type

Explanation

int

The distance between the starting coordinate point and the leftmost point, ranging from 0 to width-1

int

The distance between the starting coordinate point and the top edge, ranging from 0 to height-1

int

The distance between the end coordinate point and the leftmost point, ranging from 0 to width-1

int

The distance between the end coordinate point and the top, ranging from 0 to height-1

int

Optional, color, the default is 0

Return Value

return value type

explanation

bool

Painting success will return true

Examples

rerult = buff:drawLine(0,0,2,3,0xffff)

buff:drawRect(x1,y1,x2,y2,color,fill)#

Draw a rectangle (regardless of the current pointer position; the pointer position does not change after execution)

Parameters

Incoming Value Type

Explanation

int

The distance between the starting coordinate point and the leftmost point, ranging from 0 to width-1

int

The distance between the starting coordinate point and the top edge, ranging from 0 to height-1

int

The distance between the end coordinate point and the leftmost point, ranging from 0 to width-1

int

The distance between the end coordinate point and the top, ranging from 0 to height-1

int

Optional, color, the default is 0

bool

Optional, whether to fill inside, default nil

Return Value

return value type

explanation

bool

Painting success will return true

Examples

rerult = buff:drawRect(0,0,2,3,0xffff)

buff:drawCircle(x,y,r,color,fill)#

Draw a circle (regardless of the current pointer position; the pointer position does not change after execution)

Parameters

Incoming Value Type

Explanation

int

**The distance between the center of the circle **and the leftmost, ranging from 0 to width-1

int

**The distance between the center of the circle **and the top edge, ranging from 0 to height-1

int

radius of circle

int

Optional, the color of the circle, the default is 0

bool

Optional, whether to fill inside, default nil

Return Value

return value type

explanation

bool

Painting success will return true

Examples

rerult = buff:drawCircle(15,5,3,0xC)
rerult = buff:drawCircle(15,5,3,0xC,true)

buff[n]#

Read and write data in the form of following mark (regardless of the current pointer position; the pointer position will not change after execution)

Parameters

Incoming Value Type

Explanation

int

What data, subscript starting with 0 (C standard)

Return Value

return value type

explanation

number

Data for this location

Examples

buff[0] = 0xc8
local data = buff[0]

buff:free()#

Release the memory applied by zbuff Note: gc will automatically release zbuff and the memory applied by zbuff, so it is usually not necessary to call this function. Please make sure you know the use of this function before calling! Calling this function will not release zbuff, but will only release the memory applied by zbuff. zbuff will automatically release it when gc!!!

Parameters

None

Return Value

None

Examples

buff:free()

buff:resize(n)#

Adjust the size of zbuff’s actual allocated space, similar to the effect of realloc, new = realloc(old, n), which can be expanded or reduced (if len is less than used after reduction, then used = new len)

Parameters

Incoming Value Type

Explanation

int

New Space Size

Return Value

None

Examples

buff:resize(20)

buff:copy(start, para,…)#

zbuff Dynamic data writing, similar to the memcpy effect, when the original space is insufficient, dynamic expansion of space

Parameters

Incoming Value Type

Explanation

int

Write the starting position of buff, if it is not a number, it is used of buff, if it is less than 0, it is counted forward from used,-1 = used - 1

any

The data written to buff is one parameter when string or zbuff is used, and multiple parameters when number is used.

Return Value

return value type

explanation

number

Length of data successfully written

Examples

local len = buff:copy(nil, "123") -- Similar to memcpy(& buff[used], "123", 3) used = 3 writes data from buff, and the pointer moves back accordingly
local len = buff:copy(0, "123") -- Similar to memcpy(& buff[0], "123", 3) if (used < 3) used = 3 writes data from position 0, the pointer may move
local len = buff:copy(2, 0x1a,0x30,0x31,0x32,0x00,0x01)  -- Similar to memcpy(& buff[2], [0x1a,0x 30,0x 31,0x 32,0x 00,0x 01], 6) if (used < (2 6)) used = (2 6) starts from position 2 and writes multiple bytes of data by value
local len = buff:copy(9, buff2)  -- Similar to memcpy(& buff[9], & buff2[0], buff2 used) if (used < (9 buff2 used)) used = (9 buff2 used) Starting from position 9, merge the contents of 0 ~ used in buff2
local len = buff:copy(5, buff2, 10, 1024)  -- Similar memcpy(&buff[5], &buff2[10], 1024) if (used < (5+1024)) used = (5+1024)

buff:used()#

Obtain the offset from the last data position pointer in zbuff to the first address to indicate the amount of valid data in zbuff. Note that this is different from the allocated space size. Since seek() will change the last data position pointer, it will also affect the return value of used().

Parameters

None

Return Value

return value type

explanation

int

Effective data size

Examples

buff:used()

buff:del(offset,length)#

Delete a piece of data in the range of zbuff 0 to used, note that only the value of used is changed, not really clear the data in ram.

Parameters

Incoming Value Type

Explanation

int

Start position, default 0, if <0, count forward from used, such as -1 start= used - 1

int

The length del_len. The default value is used. If the value of the start del_len is greater than used, the value is forced to be adjusted.del_len = used - start

Return Value

None

Examples

buff:del(1,4)    --Delete 4 bytes of data from position 1
buff:del(-1,4)    --Delete 4 bytes of data from position used-1, but this will definitely exceed used, so the del_len will be adjusted to 1, which is actually deleting the last byte.

buff:query(offset,length,isbigend,issigned,isfloat)#

According to the starting position and length 0 ~ used range to take out the data, if it is 1,2,4,8 bytes, according to the subsequent parameters to convert to floating point or shaping

Parameters

Incoming Value Type

Explanation

int

The starting position of the data (the starting position is 0)

int

Length of data

boolean

Whether it is a big-endian format. If it is nil, it will not be converted and the byte stream will be output directly.

boolean

Is signed, the default is false

boolean

Whether it is a floating point type, the default is false

Return Value

return value type

explanation

string

Read out the data

Examples

local s = buff:query(0,5)--Read the first five bytes of data

buff:set(start, num, len)#

zbuff similar to memset operation, similar to memset(& buff[start], num, len), of course there is ram out-of-bounds protection, will have a certain limit on len

Parameters

Incoming Value Type

Explanation

int

Optional, starting position, default is 0,

int

Optional, the default is 0. value to set

int

Optional, length, default is all space, if out of range, will be automatically truncated

Return Value

None

Examples

-- Initialize all 0
buff:set() --Equivalent memset(buff, 0, sizeof(buff))
buff:set(8) --Equivalent memset(&buff[8], 0, sizeof(buff) - 8)
buff:set(0, 0x55) --Equivalent memset(buff, 0x55, sizeof(buff))
buff:set(4, 0xaa, 12) --etc. are used memset(&buff[4], 0xaa, 12)

buff:isEqual(start, buff2, start2, len)#

zbuff is similar to the memcmp operation, similar memcmp(&buff[start], &buff2[start2], len)

Parameters

Incoming Value Type

Explanation

int

Optional, starting position, default is 0,

zbuff

Object of Comparison

int

Optional, the starting position of the compared object, the default is 0

int

Comparison Length

Return Value

return value type

explanation

boolean

true Equal, false not equal

int

Equal returns 0, unequal returns the ordinal number of the first unequal position

Examples

local result, offset = buff:isEqual(1, buff2, 2, 10) --Equivalent memcmp(&buff[1], &buff2[2], 10)