材质库SDK说明

简介

材质库对外提供C++端SDK，包括用户权限验证、库管理、材质管理、本地缓存管理等底层功能。用户可以基于材质库SDK提供的用户接口，搭建材质库应用界面，拉取云端材质数据，以实现产品个性化的业务功能。

功能介绍

1. 支持网络产品的用户权限认证。
2. 支持产品库、材质分类、材质列表等信息获取。
3. 支持材质数据的上传和下载。
4. 支持云端材质的本地缓存功能。
5. 支持本地缓存数据的读写与访问。
6. 支持同一产品多引擎数据一致性。
7. 支持用户自定义材质库网页版界面。
8. SDK的本地服务模块支持不依赖产品的独立发版。

获取SDK

点击此处 获取新版本的SDK包。

SDK集成说明

SDK根据“客户-服务端”的思想进行开发，分为两部分。

1、“服务端”模块：独立exe安装文件，开发调试时双击安装即可，如果产品集成了材质库模块，则需要在产品的安装包中增加此exe文件并随产品安装，安装成功之后以系统服务的方式始终保持运行状态，以便支持“客户端”的请求；

2、“客户端”模块：包含Include、Bin、Lib三部分，需要产品在开发时引入到工程中，以便调用SDK提供的用户接口。

SDK接口说明

CMaterialRequestHandler.h

导出类所在头文件，提供SDK所有导出接口。

1、SDK导出类的构造函数

CMaterialRequestHandler(const QString& engineType, const QString& userToken, const QString& clientVersion = "");

说明

如果用户需要调用SDK的接口操作材质数据，需要创建此类的对象，通过类对象调用函数如：

CMaterialRequestHandler pHandler = new CMaterialRequestHandler("GGP", "cn-7ae9062a-f3d0-4ab5-a08c-4b6fb6889197");
pHandle->GetMaterialProperties(materialId);

参数

参数名	输入/输出	描述
engineType	@param in	引擎类型（有限枚举）
userToken	@param in	用户token
clientVersion	@param in	“客户端”动态库版本号

2、获取指定id材质的属性文件（json）

QString GetMaterialProperties(const QString& libId, const QString& matId);

说明

通过该接口可以返回本地缓存中材质属性文件的内容。

参数

参数名	输入/输出	描述
libId	@param in	材质所在的库id
matId	@param in	材质id
返回值	@return	属性列表字符串， 找不到时返回空。

3、获取指定id材质的资源文件路径

    QString GetMaterialResourcePath(const QString& libId, const QString& resourceId);

说明

通过该接口可以返回本地缓存材质的各种纹理贴图的路径。

参数

参数名	输入/输出	描述
libId	@param in	纹理贴图所属材质所在的库id
resourceId	@param in	资源id
返回值	@return	获取到的资源文件路径，找不到资源时返回空

4、获取指定id材质的缩略图本地缓存路径

QString GetThumbnailPath(const QString& libId, const QString& matId);

说明

通过该接口可以返回本地缓存中的缩略图路径。

参数

参数名	输入/输出	描述
libId	@param in	缩略图所属材质所在的库id
matId	@param in	缩略图id（与材质id一致）
返回值	@return	获取到的文件缓存路径，找不到缩略图时返回空

5、判断材质是否已经缓存到本地

bool IsMaterialInCache(const QString& libId, const QString& matId, const QString& engineType, IViewAdapter* pAdapter);

说明

该接口判断材质是否已经缓存到本地，SDK本身不理解下载的材质属性文件，需要用户实现材质解析的回调方法

参数

参数名	输入/输出	描述
libId	@param in	材质所在的库id
matId	@param in	材质id
engineType	@param in	引擎类型（有限枚举）
pAdapter	@param in	回调适配类（由调用方实现对应的接口，定义回调行为）
返回值	@return	已缓存返回true，否则返回false

6、获取产品自定义库列表

void GetLibraryList(const QString& version, IViewAdapter* pAdapter);

说明

该接口为异步调用，下载完成后在回调方法中获取返回结果并执行用户自定义操作。目前一般产品都只有一个产品库，由版本号指定。

参数

参数名	输入/输出	描述
version	@param in	产品库的版本号（由材质库管理员在后台创建产品库时指定）
pAdapter	@param in	回调适配类

7、获取当前库的分类列表

void GetCategoryListByLibraryId(const QString& libraryId, IViewAdapter* pAdapter);

说明

该接口为异步调用，下载完成后在回调方法中获取返回结果并执行用户自定义操作。此接口只返回一级分类列表。

参数

参数名	输入/输出	描述
libraryId	@param in	材质所在的库id
pAdapter	@param in	回调适配类

8、获取当前分类下的材质列表

void RequestMaterialListByCategory(const QString& libId, const QString& catergoryId, IViewAdapter* pAdapter);

说明

该接口为异步调用，下载完成后在回调方法中获取返回结果并执行用户自定义操作

参数

参数名	输入/输出	描述
libId	@param in	材质所在的库id
catergoryId	@param in	一级分类id（此参数来源于上一个接口的返回数据）
pAdapter	@param in	回调适配类

9、下载材质数据

void DownloadMaterial(const QString& libId, const QString& matId, IViewAdapter* pAdapter, int queueType = 0);

说明

该接口为异步调用，下载完成后在回调方法中获取返回结果并执行用户自定义操作

参数

参数名	输入/输出	描述
libId	@param in	材质所在的库id
matId	@param in	材质id
pAdapter	@param in	回调适配类
queueType	@param in	0-默认值 清空之前缩略图下载的队列, 1-新请求的内容排在队尾，2-新内容排在队头

10、批量下载材质缩略图

void DownloadThumbnailsById(const QString& libId, const QString& ids, IViewAdapter* pAdapter, int queueType = 0);

说明

该接口为异步调用，下载完成后在回调方法中获取返回结果并执行用户自定义操作

参数

参数名	输入/输出	描述
libId	@param in	材质所在的库id
ids	@param in	材质id列表（id以分号';'隔开）
pAdapter	@param in	回调适配类
queueType	@param in	0-默认值 清空之前缩略图下载的队列, 1-新请求的内容排在队尾，2-新内容排在队头

11、创建材质库对话框

QString CreateChildWindow(const QString& engineType, const QString& htmlPath, HWND parent);

说明

该接口根据用户提供的html5文件创建浏览器子窗口并返回句柄给父窗口。

参数

参数名	输入/输出	描述
engineType	@param in	引擎类型（有限枚举）
htmlPath	@param in	html5压缩包的全路径
parent	@param in	父窗口句柄

IViewAdapter.h(回调类)

回调类，提供异步接口返回成功或失败时对应的回调方法，具体功能由调用层实现。

所有回调函数

class IViewAdapter
{
public:
    // Download callback
    virtual void onLibraryListLoadProgress(const QString& result) = 0;
    virtual void onCategoryListLoadProgress(const QString& result) = 0;

    virtual void onMaterialListLoadProgress(const QString& result) = 0;
    virtual void onMaterialLoadProgress(const QString& result, const float progress) = 0;
    virtual void onThumbnailLoadProgress(const QString& result) = 0;


    //StatusCode.Normal = 0;
    //StatusCode.ErrorTimeout = 6000;
    //StatusCode.ErrorPrivilege = 7000;
    //StatusCode.ErrorNotexist = 8000;
    //StatusCode.ErrorNetwork = 9000;
    virtual void onLibraryListLoadError(const QString& result, const int statusCode) = 0;
    virtual void onCategoryListLoadError(const QString& result, const int statusCode) = 0;

    virtual void onMaterialListLoadError(const QString& result, const int statusCode) = 0;
    virtual void onMaterialLoadError(const QString& result, const int statusCode) = 0;
    virtual void onThumbnailLoadError(const QString& result, const int statusCode) = 0;

    // Parse callback
    virtual QString ParseJson(const QString& Json) = 0;
};