PISOFTTECH 圆周率全景相机 Android SDK 使用指南 版本 :V0.9.0.DOUBLE Louise 本文主要指导用户如何将本公司的 Android SDK 集成到自己的 Android 项目中, 及提供 API 说明
目录 一 功能介绍...3 1. 功能列表...3 2. 使用限制...3 二 Android studio 如何导入 SDK... 3 1. SDK 文件结构... 3 2. 导入必要文件...4 3. 工程配置...6 三 调用 SDK... 9 1. 初始化...9 2. 如何开始预览...10 3. 如何查看本地照片...10 4. 如何播放视频...10 四 API 说明... 11 初始化...11 int init(activity actvty)...11 View getplayerview()...11 void setsdkisreadylistener(onsdkisreadylistener listener)...11 实时预览...12 void setpreviewisreadylistener(onpreviewisreadylistener listener)...12 int startpreview()...12 int stoppreview()... 12 void setpreviewtexturesize(int width, int height)...12 SurfaceTexture getpreviewsurfacetexture()... 13 视频文件播放...13 int openvideo(string url)...13 void pause()...13 void Resume()...13 void stop()...14 double getvideoprogress()...14 void seek(double offset)...14 查看本地照片...14 int openphoto(string path)... 14 显示效果...15 int setshowmode(int showmode)...15 其他...15 String getversion()... 15
一 功能介绍 1. 功能列表 功能 实时预览浏览图片播放全景视频 描述 以多种全景预览模式, 观看全景相机拍摄的实时图像以多种全景观看模式, 查看本地保存的全景照片以多种全景观看模式, 播放本 SDK 录制的全景视频文件 2. 使用限制 软件要求 : 只支持 android 5.0 及以上 armeabi-v7a 版本的 android 应用开发 硬件要求 : 要求 CPU 四核 2.7GHz, 运行时内存 2GB 同等及以上性能的手机 二 Android studio 如何导入 SDK 1. SDK 文件结构 下图 : pi_camera_sdk.zip 解压后会得到 libs assets jnilibs demo doc 三个文件夹, 如 其中 :
件 ; libs assets 及 jnilibs 文件夹包含的是 android 工程集成 SDK 的必须文 demo 包含的是 android studio 调用 SDK 的实例工程 ; doc 包含的是 SDK 的帮助文档 2. 导入必要文件 1) 将 libs 目录下的所有文件复制到 android studio 工程的 libs 目录中, 如下图 : 图中文件仅供参考, 实际文件会根据使用前版本有所差异 2) 将 assets 文件夹复制到 android studio 工程的 src/main 目录中, 如下图 :
3) 将 jnilibs 目录下的文件夹复制到 android studio 工程的 src/main/jnilibs 目录 ( 如果没有 jinilibs 目录, 则新建一个 ) 中, 如下图 :
图中文件仅供参考, 实际文件会根据使用前版本有所差异 3. 工程配置 用户须要根据实际需求, 配置相应的权限 以 demo 中的实例工程为例, 拍照 录像须 要 SD 卡的读写及音频采集权限, 如下图 :
在需要嵌入预览或播放器的 layout 文中加入一个播放器的父控件, 如 LinearLayout, 参 考下图 : 在 Activity 的 oncreate() 中加入 LinearLayout layout = (LinearLayout)findViewById(R.id.videoview); layout.addview(panoplayerview); layout 变量对应上面 layout 中添加的控件,panoPlayerView 变量由 SDK 的 API 中获得, 详见下文 重载 Activity 中以下函数 :
@Override protected void ondestroy () mpipanosdk.ondestroy(); super.ondestroy(); // Pause Unity @Override protected void onpause() super.onpause(); mpipanosdk.onpause(); // Resume Unity @Override protected void onresume() super.onresume(); mpipanosdk.onresume(); // This ensures the layout will be correct. @Override public void onconfigurationchanged(configuration newconfig) super.onconfigurationchanged(newconfig); mpipanosdk.onconfigurationchanged(newconfig); // Notify Unity of the focus change. @Override public void onwindowfocuschanged(boolean hasfocus) super.onwindowfocuschanged(hasfocus); mpipanosdk.onwindowfocuschanged(hasfocus); mpipanosdk 变量由 SDK 的 API 中获得, 详见下文
三 调用 SDK 1. 初始化 1) 先在要调用 SDK 的 java 文件中加入 import com.pi.rendertexturetoencoder.texturelistener; import com.pi.pipanosdk.errcode; import com.pi.pipanosdk.pipanosdk; 2) 在 Activity 的 oncreate() 中加入创建 SDK 对象 mpipanosdk = new PiPanoSDK(); 3) 设置监听 SDK 初始化是否完成 mpipanosdk.setsdkisreadylistener(this); // 设置监听 SDK 初始化是否完成 4) 加入以下代码初始化 SDK int ret = 0; ret = mpipanosdk.init(this); if (ret!= ErrCode.SUCCESS) Log.e(TAG, "mpi_panoplayer.init() failed!, ret = " + ret); return; 5) 获取 SDK 图像渲染窗口 View panoplayerview = mpipanosdk.getplayerview(); if (null == panoplayerview) Log.e(TAG, "null == panoplayerview"); return; 6) 实现接口 PiPanoSDK.OnSDKIsReadyListener 中的 onsdkisready(), 监听 SDK 初始化完成 public void onsdkisready() msdkisok = false; Log.d(TAG, "SDK is ok");
2. 如何开始预览 1) 使用 setpreviewisreadylistener() 设置监听预览是否准备就绪 ; 2) 实现 OnPreviewIsReadyListener() 方法 ; 3) 调用 setpreviewtexturesize() 设置 SDK 预览的 texture size; 4) 调用 setshowmode() 设置显示模式 ; 5) 调用 startpreview() 开始预览 ; 6) OnPreviewIsReadyListener() 响应后, 调用 getpreviewsurfacetexture() 获取 SDK 的 SurfaceTexture, 然后将图像渲染到此 SurfaceTexture, 即可预览到图像 ; 7) 在预览过程中可调用 setshowmode() 切换预览模式, 详见 API 说明 ; 8) 调用 stoppreview() 停止预览 3. 如何查看本地照片 1) 查看本地照片调用 openphoto() 打开指定的本地照片, 并显示在之前关联的控件中 注意 : A. 调用 openphoto() 前必须已调用 setshowmode() 设置了显示模式 2) 在照片浏览时, 可以调用 setshowmode() 切换浏览模式 4. 如何播放视频 1) 播放录像 A. 调用 openvideo() 打开视频文件, 可以是本地文件也可以是网络 url 注意 : a) 在调用 openvideo() 前必须已调用 setshowmode() 设置了显示模式 B. 在播放过程中, 可以调用 setshowmode() 切换浏览模式 C. 调用 pause() 暂停播放 D. 调用 resume() 继续播放 E. 调用 getvideoprogress() 获取当前播放进度百分比 (1.0 表示 100%)
F. 调用 seek() 快进到指定的进度百分比开始播放 G. 调用 stop() 停止视频播放 四 API 说明 初始化 int init(activity actvty) 初始化 SDK Parameters actvty 使用 SDK 的 actvty 返回 0 表示成功就, 返回负值表示失败 View getplayerview() 获取 SDK 用于图像渲染的 view, 以便部署到 android 工程的 UI 中 返回 null 表示失败 void setsdkisreadylistener(onsdkisreadylistener listener) 给 SDK 绑定 OnSDKIsReadyListener, 以便监听 SDK 初始化是否完成 Parameters listener
实时预览 void setpreviewisreadylistener(onpreviewisreadylistener listener) 给 SDK 绑定 OnPreviewIsReadyListener, 以便监听预览是否准备就绪 Parameters listener int startpreview() 开始显示预览图像 返回 0 表示成功就, 返回负值表示失败 int stoppreview() 停止显示预览图像 返回 0 表示成功就, 返回负值表示失败 void setpreviewtexturesize(int width, int height) 设置预览 Texture 的 size
SurfaceTexture getpreviewsurfacetexture() 获取用于渲染预览图像的 SurfaceTexture, 用户可以对此 SurfaceTexture 进行操作 用于渲染预览图像的 SurfaceTexture 视频文件播放 int openvideo(string url) 打开并播放视频文件 ( 支持本地和网络 ) Parameters url 本地视频文件路径或者网络链接 返回 0 表示成功就, 返回负值表示失败 void pause() 暂停播放 void Resume() 继续播放
void stop() 停止播放 double getvideoprogress() 获取视频当前播放进度的百分比 视频当前播放进度的百分比 ( 范围 :0.0~1.0) void seek(double offset) 进度跳转 Parameters offset 表示跳转到视频时长的百分之几的位置 ( 范围 :0.0~1.0) 查看本地照片 int openphoto(string path) 打开并显示照片 Parameters path 本地视频文件路径或者网络链接
返回 0 表示成功就, 返回负值表示失败 显示效果 int setshowmode(int showmode) 设置显示模式 Parameters showmode 对应各种全景显示模式的枚举值 ( 鱼眼 VR 小行星等) 取值范围 : 全景模式 值 沉浸式 9 鱼眼 10 小行星 11 VR 分屏 12 其他 String getversion() 获取当前 SDK 版本号 当前 SDK 版本号