VRPIE_SDK 简明操作手册

简介：

    相对于一个月前发布的VRPIE插件版本，中视典的VRPIE针对最近部分用户提出的需求，开发了带编程接口的VRPIE插件（下面简称VRPIE-SDK）。通过VRPIE-SDK，嵌入ie浏览器的VRPIE插件就可以和ie页面进行交互，或者说，通过javascript就能控制VRPIE插件所装载的场景了。

    我们可以先通过一个例子(点击查看)建立对VRPIE-SDK基本的印象，后面我们会就具体操作步骤进行详细讲解。( 相信看过这个例子后，做过网页编程的通过查看页面源代码就能看到很多调用细节了)
    这个例程演示了VRPIE-SDK的几个重要功能:
        1 使用VRPIE在IE浏览器中显示三维场景。
        2 通过VRPIE-SDK提供的接口实现html的按钮等界面元素来控制vrp窗口中的场景。
        3 通过VRPIE-SDK提供的事件回调机制将vrp窗口中执行的操作，比如点击鼠标等送到外部ie浏览器中。使得IE页面中的javascript可以获得和使用这些信息。

        附案例截图，点击可查看大图

如果你有使用flash或者其他ie插件接口的开发经验,从这个例子中,你就能了解很多VRPIE-SDK的调用方式。后面我们会根据例子讲解具体的使用，重点在介绍VRPIE-SDK的接口和调用方法，关于html/javascript语法和VRP-Builder的基本操作，请查阅相关文档，此处不作重点介绍。

返回顶层目录

VRPIE-SDK接口详解：

    VRPIE-SDK是工作在VRP内核基础上通过开发和开放得到的。因此，VRPIE-SDK虽然只提供了有限的函数，但通过和VRP脚本引擎的结合使用，却可以实现强大的控制和丰富的效果。

    如同简介里所介绍的,VRPIE-SDK主要完成的三个功能为:
        1 使用VRPIE在IE浏览器中显示三维场景。
        2 通过VRPIE-SDK提供的接口实现html的按钮等界面元素来控制vrp窗口中的场景。
        3 通过VRPIE-SDK提供的事件回调机制将vrp窗口中执行的操作，比如点击鼠标等送到外部ie浏览器中。使得IE页面中的javascript可以获得和使用这些信息。

    对于VRPIE-SDK的使用，主要注意以下几个参数和接口的使用或者调用：

    1 参数 VrpieFile 。这个是指嵌入IE的vrpie插件要装在web vrp文件的名称。
    在上面的网页示例中可以看到如下的html代码：
<object classid='clsid:5C9AB67D-90EC-4DC9-A5DC-548FDDA3CDBF' id='Vrpie1' width=100% height=100% codebase='http://www.vrpie.com/vrpie/player/Vrpie.CAB#version=8,2,18,0'>
<param name='VrpieFile' value='switch.vrpie.jpg'>
</object>
    这句话也演示了如何将vrpie插件嵌入ie中。

    2 ExecuteVrpScript 函数。该函数将执行一条由其参数指定的VRP脚本函数。并将执行得到的结果返回回来。带一个字符串类型参数，表示要执行的VRPIE-SDK的脚本命令（关于脚本命令，可参考下一个章节VRP脚本参数手册）；返回值也是字符串类型，表示该脚本命令执行的结果，具体意义有当前执行的脚本命令而定（可参考 VRP脚本参数手册中相关内容）。
    下面是示例中的相关javascript代码：
function run_lines(str_lines)
{
window.Vrpie1.ExecuteVrpScript(str_lines);
}
    示例页面中对这个函数进行了封装，并且没有关心返回值。

function on_radio_clicked(obj)
{
run_lines("设置物体的状态值, level[0], "+ obj.value);
run_lines("执行内部函数, update_level_btns");
}

    演示了使用上面封装的函数。

    3 OnVrpEvent函数。事件回调机制的主要函数。在插件中触发相应的事件后，会通过这个函数送出来。带五个参数。第一个是消息id，含义可参考 VRPIE-SDK的消息回调详解。第二，三，四，五是对应消息传出的附加参数。不一定都使用，但通常的，第二个参数p1经常是当前操作目标模型的名称。
    在示例中，你可以看到如下代码：
<object classid='clsid:5C9AB67D-90EC-4DC9-A5DC-548FDDA3CDBF' id='Vrpie1' width=100% height=100% codebase='http://www.vrpie.com/vrpie/player/Vrpie.CAB#version=8,2,18,0'>
<param name='VrpieFile' value='switch.vrpie.jpg'>
</object>
<script for="Vrpie1" event="OnVrpEvent(msg,p1,p2,p3,p4)" language="Jscript">
{
if(msg <= 307)
{
var str1 = window.Vrpie1.GetVrpMsgDesc(msg,p1,p2,p3,p4);
window.textarea.value = str1 + "\r\n" + window.textarea.value;
}
}
</script>     在这段代码中，GetVrpMsgDesc 也是VRPIE插件自带的函数，使用内部方法将消息格式化，可以用来调试。

    4 FromLongAddressToString 辅助函数。在脚本回调函数中，所有的字符串都传递的是字符串首地址（指针），为了便于检验，我们提供了一个内部测试的函数FromLongAddressToString。它是将一个数字（字符串地址）转化为字符串。

    返回顶层目录

VRP脚本参数手册：

    VRP中支持上百条的单独功能的脚本函数，这些脚本还可以任意组合，实现更复杂的功能，使得我们控制起来相当强大和方便。限于篇幅，这里不在一一介绍。查看具体的脚本参数手册，可参考脚本手册(pdf文档)。脚本函数的使用，单看文档是远远不够的，它们都可以直接在VRP-Builder中测试熟悉。只有熟练掌握了VRP的脚本含义，才能真正实现自己想要的功能。

    下图是VRP-Builder中脚本编辑器的截图，可以作为测试和熟悉VRP脚本的的工具。

VRPIE-SDK的消息回调详解：

VRP的内核采用了消息机制来处理很多事情。作为VRPIE-SDK的主要功能之一，VRPIE-SDK也开放了部分消息供用户在回调函数中使用。下面是这些回调消息的信息：

MSG ID	MSG	MSG DESC	P1	P2	P3	P4
103	VMSG_MOUSE_DBCLICK	在VRP场景中鼠标左键双击事件	操作模型名称	操作模型的选中状态
200	VMSG_HOT_MODEL_LBTN_DOWN	鼠标在热点模型上左键按下	操作模型名称
201	VMSG_HOT_MODEL_LBTN_UP	鼠标在热点模型上左键弹起	操作模型名称
202	VMSG_HOT_MODEL_MBTN_DOWN	鼠标在热点模型上中键按下	操作模型名称
203	VMSG_HOT_MODEL_MBTN_UP	鼠标在热点模型上中键弹起	操作模型名称
204	VMSG_HOT_MODEL_RBTN_DOWN	鼠标在热点模型上右键按下	操作模型名称
205	VMSG_HOT_MODEL_RBTN_UP	鼠标在热点模型上右键弹起	操作模型名称
206	VMSG_HOT_MODEL_MOUSE_ENTER	鼠标移入热点模型范围	操作模型名称
207	VMSG_HOT_MODEL_MOUSE_LEAVE	鼠标移出热点模型范围	操作模型名称
300	VMSG_HOT_PANEL_LBTN_DOWN	鼠标在热点面板上左键按下	操作模型名称
301	VMSG_HOT_PANEL_LBTN_UP	鼠标在热点面板上左键弹起	操作模型名称
302	VMSG_HOT_PANEL_MBTN_DOWN	鼠标在热点面板上中键按下	操作模型名称
303	VMSG_HOT_PANEL_MBTN_UP	鼠标在热点面板上中键弹起	操作模型名称
304	VMSG_HOT_PANEL_RBTN_DOWN	鼠标在热点面板上右键按下	操作模型名称
305	VMSG_HOT_PANEL_RBTN_UP	鼠标在热点面板上右键弹起	操作模型名称
306	VMSG_HOT_PANEL_MOUSE_ENTER	鼠标移入热点面板范围	操作模型名称
307	VMSG_HOT_PANEL_MOUSE_LEAVE	鼠标移出热点面板范围	操作模型名称

快速建立一个使用VRPIE-SDK的例子:

    通过上面的介绍，大家应该对VRPIE-SDK有一个初步的印象了。下面我们将从头到尾建立一个VRPIE-SDK的应用(示例所用应用，都可以在此下载)，来熟悉和上面的函数。

    1.先决条件。
        要创建一个使用VRPIE-SDK的例子，你需要有支持输出VRPIE-SDK文件的VRP-Builder软件；如果你想在互联网观看网上效果，您还需要支持www服务的一个网络服务器空间；当然，要建模的话，max软件也是少不了的。

    2.创建一个简单的VRP场景文件
        为了简便起见，我们准备了一个简单的场景文件demo.vrp,需要的可以点击下载。场景在vrp中表现如下：(点击查看大图)

    3、将VRP文件导出为可网络发布的WEB VRP文件
        选择工具栏上的按钮

输出为可网络发布的vrpie按钮，点击。
在弹出的目录选择窗口选择你要保存的VRPIE文件的路径。点击OK（确定）。

        在弹出的VRPIE文件选项上设置文件参数，和上一个版本不同的是，这次多了2个选项。
        VRPIE的扩展标志，由于某些客户没有自己的网络服务器，在将vrpie文件上传至共享空间后，由于服务器下载文件名的限制，vrpie不能被识别和下载。因此，我们在这个版本中允许客户指定vrpie的扩展名（比如说指定为.txt .htm 等等），从而避开这个限制。
        同时注意勾选上 支持js/vbs网页脚本开发接口。

点击ok(确定),此时就会在你指定的目录产生几个文件和一个目录了。

此时双击vrpie_file.htm, 也能看到刚才的三维场景在ie中显示了。这可不是二维的平面图了，实实在在的三维可漫游的场景啊。

        察看刚才htm文件代码,如下
<HTML><head><meta http-equiv="Content-Language" content="zh-cn">
<title>VRPIE 三维网页插件演示</title>
</head>
<p>
<script type="text/javascript" src="http://www.vrpie.com/vrpie/player/ocx.js"></script>
<script language="javascript">vrp_init_pars("vrpie_file.vrpie.jpg");</script>
</p>
</HTML>

        呵呵,关键就在vrp_init_pars("vrpie_file.vrpie.jpg");和文件http://www.vrpie.com/vrpie/player/ocx.js了.从ocx.js中可以看到vrp_init_pars的定义
function vrp_init_pars(filename)
{
document.write("<body topmargin='0' leftmargin='0' rightmargin='0' bottommargin='0'><object classid='clsid:5C9AB67D-90EC-4DC9-A5DC-548FDDA3CDBF' id='Vrpie1' width='100%' height='100%' codebase='http://www.vrpie.com/vrpie/player/Vrpie.CAB#version=8, 2, 18, 0'>");
document.write("<param name='VrpieFile' value='"+filename+"'>");
document.write("</object></body>");
}

    4、对上例进行改进，添加html界面控制元素
        下面,我们将对这个案例进行改进,来熟悉ExecuteVrpScript函数的使用。在vrpie_file.htm 同级目录下，新建一个空的htm文件vrpie_file2.htm(可在同级目录找到)，类似flash的处理将ocx控件加入，同时加入2个按钮，准备调用。页面代码准备如下：
<HTML><head><meta http-equiv="Content-Language" content="zh-cn">
<title>VRPIE 三维网页插件演示</title>
</head>
<body>

<object classid='clsid:5C9AB67D-90EC-4DC9-A5DC-548FDDA3CDBF' id='Vrpie1' width=41% height=55% codebase='http://www.vrpie.com/vrpie/player/Vrpie.CAB#version=8,2,18,0'>
<param name='VrpieFile' value='vrpie_file.vrpie.jpg'>
</object>
<input name="test" type="button" value="显示" onclick="window.Vrpie1.ExecuteVrpScript('显示隐藏物体, 1, 楼5, 1')">
<input name="test2" type="button" value="隐藏" onclick="window.Vrpie1.ExecuteVrpScript('显示隐藏物体, 1, 楼5, 0')" >
</body>
</HTML>

    在本地或者网络打开文件,点击按扭看看,是否能够操作模型了呢?

    显示隐藏物体, 1, 楼5, 0 / 显示隐藏物体, 1, 楼5, 1 ,是VRP中的脚本函数. 意思是显示/隐藏模型,该模型的名字是楼5

    5、添加事件回调函数，让VRP中的操作可以送到IE中来。
    下面,我们在vrpie_file2.htm上继续添加代码,使其能够获得并处理VRPIE控件的消息（这些代码可在同级目录vrpie_file3.htm中找到）。
<HTML><head><meta http-equiv="Content-Language" content="zh-cn">
<title>VRPIE 三维网页插件演示</title>
</head>
<body>

<object classid='clsid:5C9AB67D-90EC-4DC9-A5DC-548FDDA3CDBF' id='Vrpie1' width=41% height=55% codebase='http://www.vrpie.com/vrpie/player/Vrpie.CAB#version=8,2,18,0'>
<param name='VrpieFile' value='vrpie_file.vrpie.jpg'>
</object>
<script for="Vrpie1" event="OnVrpEvent(msg,p1,p2,p3,p4)" language="Jscript">
{
if(msg == 103)
{
alert("你刚才点了模型 <"+ window.Vrpie1.FromLongAddressToString(p1) +"> 哟！"); }
}
</script>
<input name="test" type="button" value="显示" onclick="window.Vrpie1.ExecuteVrpScript('显示隐藏物体, 1, 楼5, 1')">
<input name="test2" type="button" value="隐藏" onclick="window.Vrpie1.ExecuteVrpScript('显示隐藏物体, 1, 楼5, 0')" >
</body>
</HTML>

    在场景中点击模型后效果如下：

高级应用，VRPIE和数据库的连接：

中视典数字科技有限公司@2006

http://www.vrplatform.com/

目录：

简介：

VRPIE-SDK接口详解：

VRP脚本参数手册：

VRPIE-SDK的消息回调详解：

快速建立一个使用VRPIE-SDK的例子:

高级应用，VRPIE和数据库的连接：