zbuff - c Memory Data Manipulation Library#
Adapted Air780E/Air700E Air780EP 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)