IMGobject类 - Lucky-Koishi/KoishiExAPI GitHub Wiki

namespace Koishi;
└class IMGobject;

　　IMGobject类(其实例可称为"IMG对象")允许您将本地IMG文件进行解析和修改，目前支持的版本有2、4、5和6，解析后的结果会保存在IMG对象的各种属性中。通过IMG对象，您可以得知其包含的图片信息（图片型索引项）以及提取图像数据；若IMG对象的版本是4或6，您也可以得知其调色板相关信息；若IMG对象的版本是5，您也可以得知其包含的DDS索引信息和图片信息；您还可以使用已有的贴图数据等信息，对IMG对象进行更改。
　　例如，以下代码用于提取已知IMG文件内的贴图为PNG图像：

IMGobject io("demo.img");
matrix mat;
if(io.indexCount > 4){
　　io.PICextract(4, mat); // 提取IMG的第四帧贴图
　　mat.makePNG("4th_frame_of_demo.png"); //将贴图保存为PNG文件
}

　　又例如，以下代码用于新建一个V4版本的IMG对象，并尝试向其中插入一个PNG贴图；值得注意的是V4版本的IMG对象在进行贴图插入操作时，需要进行预处理工作，例如扩充调色板容量等：

IMGobject io;
matrix mat;
stream s; //插入贴图操作需要的数据流
PICinfo pi; //插入贴图操作需要的图片型索引项
io.Create(V4);
mat.loadPNG("bunny.png");
if(!io.PICprogress(mat, s, pi)) //图像预处理，并生成贴图需要的索引项和数据流
　　printf("Not enough size for palette.");
else{
　　io.PICpush(pi, s); //将贴图插入到IMG中
　　io.SaveFile("myBunny.img");//保存IMG文件
}

　　IMG对象是整个EX系统的核心，具有最为复杂的结构和操作方式，其操作方式严格依赖于IMG对象的版本；所幸，IMGobject类的大部分函数都可以对当前的IMG对象的版本进行识别并根据版本的不同进行不同的工作，但函数执行不一定全部成功，因此在调用该类大部分函数时，应尽量对函数返回值进行判断，确保函数执行成功时再进行后续工作。
　　IMGobject类包含多种属性，有的属性只有在特定的版本有意义并被赋值，而在其他版本没有意义————尽管该属性仍然可以被有意义地赋值，例如IMGobject::V5_totalLength属性，在V5中表示该IMG的总长度，在其他版本没有意义（但是依然可以使用“总长度”来对其进行赋值，所以为了声明其仅在V5有效，才在标识符前加上V5_的前缀）。对IMGobject类内部的所有属性，均不应该使用左值赋值的方式去修改它，否则会破坏属性值与缓冲区内数据的一致性。
　　每个IMG对象均包含6个缓冲区（类似于NPK对象的4个缓冲区），分别用于存储IMG首部数据、调色板数据、DDS索引项数据、图片型索引项数据、DDS图像数据、普通图像数据。**IMG对象内的函数在执行时，会对缓冲区内的数据进行同步的修改。**值得注意的是根据IMG对象的版本不同，所用到的缓冲区也是不同的，例如只有V5版本才能调用DDS索引项数据和DDS图像数据，因此如果您在处理非V5的IMG对象时试图访问这些缓冲区，运行时就会报错（因为没有为它们分配内存）。

访问权限	属性名	说明
公开	IMGversion　version	IMG对象的版本。
公开	IMGindex　*derived	当该IMG对象由NPK对象进行IMGextract()提取得到，该指针指向NPK对象内该IMG对象对应的IMG索引项；否则为NULL。
公开	b32　indexCount	包含图像型索引项的个数(帧数)。
公开	b32　indexSize	包含图像型索引表的大小。
公开	palette　paletteData	V4、V5、V6有效，调色板数据。
公开	b32　V5_totalLength	V5有效，IMG文件的大小。
公开	b32　V5_DDSCount	V5有效，包含的DDS索引项的个数。
公开	DDSlist　DDScontent	V5有效，DDS索引表(DDS索引项构成的数组)。
公开	PIClist　PICcontent	图像型索引表(图像型索引项构成的数组)。
保护	stream　data1	第一缓冲区，存储IMG文件的头部数据，包括头部表示、版本、图像型索引项的个数和图像型索引项的大小。
保护	stream　data2	第二缓冲区，V4、V5、V6有效，存储IMG文件的调色板数据。
保护	stream　data3	第三缓冲区，V5有效，存储IMG文件的DDS索引表数据。
保护	stream　data4	第四缓冲区，存储IMG文件的图片型索引表的数据。
保护	stream　data5	第五缓冲区，V5有效，存储IMG文件的DDS图像数据。
保护	stream　data6	第六缓冲区，V5有效，存储IMG文件的普通图像(包括位图和索引图)数据。

访问权限	函数名	说明
公开	IMGobject(...)	构造函数。
公开	~IMGobject(...)	析构函数。
公开	bool　LoadFile(...)	导入外部文件。
公开	bool　SaveFile(...)	存储为外部文件。
公开	bool　Load(...)	导入数据流。
公开	bool　Make(...)	将缓冲区的数据制作成数据流。
公开	bool　Create(...)	创建基于指定版本的“空IMG”对象。
公开	bool　Release(...)	释放当前IMG对象。
公开	bool　GetPICInfo(...)	获得指定位置的图片型索引项。
公开	bool　GetPICInfoOffset(...)	获得指定位置的图像型索引项数据在第四缓冲区的起始位置。
公开	bool　GetPICData(...)	获得指定位置的图片型索引项对应的图像数据。
公开	bool　GetPICDataOffset(...)	获得指定位置的图片型索引项对应的图像数据在第六缓冲区的起始位置。
公开	bool　GetDDSInfo(...)	仅V5有效，获取指定位置的DDS索引项。
公开	bool　GetDDSInfoOffset(...)	仅V5有效，获得指定位置的DDS索引项数据在第三缓冲区的起始位置。
公开	bool　GetDDSData(...)	仅V5有效，获得指定位置的DDS索引项对应的DDS贴图数据。
公开	bool　GetDDSDataOffset(...)	仅V5有效，获得指定位置的DDS索引项对应的DDS贴图数据在第五缓冲区的起始位置。
公开	bool　SetPICInfoPara(...)	对指定图片型索引项中的某些数据进行设定。
公开	bool　PICpush(...)	给定图片型索引项和图片数据流，尝试向IMG对象末端插入该贴图。
公开	bool　PICinsert(...)	给定图片型索引项和图片数据流，尝试向IMG对象中指定位置插入该贴图。
公开	bool　PICremove(...)	删除IMG对象中指定位置的贴图。
公开	bool　PICreplace(...)	给定图片型索引项和图片数据流，尝试替换IMG对象中指定位置的贴图。
公开	bool　PICextract(...)	提取指定位置的贴图数据并将其转换为像素矩阵。
公开	bool　PICpreprocess(...)	给定像素矩阵对IMG对象进行预处理，并生成适配该像素矩阵的图片型索引项和图片数据流。
公开	bool　PICempty(...)	隐藏指定位置的贴图。
公开	bool　DDSpush(...)	仅V5有效，给定DDS索引项和DDS贴图数据流，尝试向IMG对象末端插入该DDS贴图。
公开	bool　DDSinsert(...)	仅V5有效，给定DDS索引项和DDS贴图数据流，尝试向IMG对象指定位置插入该DDS贴图。
公开	bool　DDSremove(...)	仅V5有效，删除IMG对象中指定位置的DDS贴图。
公开	bool　DDSreplace(...)	仅V5有效，给定DDS索引项和DDS贴图数据流，尝试替换IMG对象中指定位置的DDS贴图。
公开	bool　DDSextract(...)	仅V5有效，提取指定位置的DDS贴图数据并将其转换为像素矩阵。
公开	bool　DDSpreprocess(...)	给定像素矩阵对IMG对象进行预处理，并生成适配该像素矩阵的DDS索引项和DDS贴图数据流。
公开	bool　CLRpush(...)	仅V4、V5、V6有效，向指定颜色方案(V4、V5默认为#0)末尾插入一个颜色数据。
公开	bool　CLRinsert(...)	仅V4、V5、V6有效，向指定颜色方案(V4、V5默认为#0)中指定位置插入一个颜色数据。
公开	bool　CLRremove(...)	仅V4、V5、V6有效，删除指定颜色方案(V4、V5默认为#0)中指定位置的颜色数据。
公开	bool　CLRreplace(...)	仅V4、V5、V6有效，将指定颜色方案(V4、V5默认为#0)中指定位置的颜色数据替换为给定颜色数据。
公开	bool　CLRnewPalette(...)	仅V6有效，新增加一个颜色方案。
公开	bool　ConvertTo(...)	将当前IMG对象版本转换为其他版本。
公开	i32　linkFind(...)	寻找指向型索引项最终指向的帧号。
公开	b64　getSize(...)	返回当前IMG对象六个缓冲区的总大小。
保护	stream　*getData(...)	根据标号返回缓冲区的地址。