From Virtools Wiki

Procedure for Creating a Standalone Player With Virtools Dev 3.5/4 & VC++ 7 (.NET 2003)

This document will illustrate the procedure for creating a standalone exe player for Virtools CMO and VMO files.
This document will assume “$VT” as the installation directory of the Virtools Dev 3.5 or Virtools Dev 4.0.

Standalone player “Linked DLL compilation”

   This player relies on external files to launch the Virtools composition or VMO in a windows executable application, it’s a single lightweight executable which calls other external resources (DLL) files in order to correctly play the Virtools file.
   Procedure:
   1) Go to $VT \Sdk\Samples\Runtime\Standalone Player\
   2) Open CustomPlayer.sln using Visual Studio 2003
   3) Build the solution.
   4) Initial build should commence with no problems as this is the most basic compilation of the player.
   5) Refer to $VT \Sdk\Temp\Win32.
   6) You will see the project built into that directory, to change the output directory in which VC++ places the generated files do the following:
   • Using the IDE, choose the solution explorer and right click on the CustomPlayer to view properties.
   • In the Configuration Properties>>General pane, change the output directory & intermediate directory values though they are inconsequential.
   • In the Linker>>General pane, change the Output File value to wherever you want the program to create the final EXE file.
   • If you build the solution as it is, it will probably work fine on your PC but will generate an MFC related error on other stations, because the current configuration is set to DEBUG, to change that configuration, go the Properties of the solution and click on Configuration Manager, change the mode to RELEASE, hit ok and build solution.
   • The exe File should be generated in the directory you specified -$VT \Sdk\Temp\Win32 by default-.
   7) Browse the directory and test the application using the following procedure, assume you are at
   $VT \Sdk\Temp\Win32\CustomPlayer\Release\:
   • Place a test –operational- CMO file at the same level of the exe generated file –CustomPlayer.exe by default- name the file TEST123.CMO.
   • Copy the following directories to the
   $VT \Sdk\Temp\Win32\CustomPlayer\Release\ directory:
   1) $VT \BuildingBlocks\
   2) $VT \Managers\
   3) $VT \Plugins\
   4) $VT \RenderEngines\
   Copy the following files to the
   $VT \Sdk\Temp\Win32\CustomPlayer\Release\ directory:
   1) $VT \CK2.dll\
   2) $VT \CKZlib.dll\
   3) $VT \VSLRT.dll\
   4) $VT \VxMath.dll\
   • Copy all of the following directory contents to the corresponding directories you copied in
   $VT \Sdk\Temp\Win32\CustomPlayer\Release\
   1) $VT \Sdk\Redist\BuildingBlocks\
   2) $VT \Sdk\Redist\Manager
   • Copy the following file to the
   $VT \Sdk\Temp\Win32\CustomPlayer\Release\ Directory:
   $VT \Sdk\Redist\VSLRT.dll
   Note that not all of the previous files and directories are required,
   you can minimize the size of the final output by selecting specific DLL’s-
   those DLL’s that are required by your composition only-
   This is a great and a very important way of doing things.
   So when you are deploying an application make sure that you copy only the files you need.
   8) Now the player should be accessible, to play the Virtools file do the following:
   • Start >> Run.
   • Type cmd and press enter.
   • Issue the commands:
   prompt>> cd $VT \Sdk\Temp\Win32\CustomPlayer\Release\
   prompt>> CustomPlayer.exe –file=TEST123.CMO –title=test –width=800 –height=900
   • The player should play the file now, if not, backtrack and make sure you have all the steps right.
   • Take a look at the readme.txt for further clarification on the parameters passed to the player.
   The previous procedure compiles a basic player of the Virtools player. The following is what might be considered the pros and cons of the compilation:
   • Pros:
   1. Ease of deployment.
   2. Ease of file transition, meaning it is suitable for playing a number of files instead of hard coding the filename and path, so if you create a batch file instead of issuing the run command at every turn, you can create a number of batch files for a number of Virtools files with different parameters.
   3. Not all of the Virtools DLL’s are required, meaning you don’t have to copy the entire contents of the BuildingBlocks, Managers, Plugins and RenderEngines, just copy the ones you need and redistribute your application accordingly.
   • Cons:
   1. The Virtools DLL’s are visible and should be present when distributing the application, this can be considered a poor approach for deploying projects with Virtools, at least to me, having everything bundled in single packages sounds a lot more practical, plus you minimize the margin of error, when a user accidentally deletes a required DLL for example.
   2. A deployed version might be tampered with, a batch file might be reconfigured to play a file with a parameter set other than the original one, and I strongly recommend that this approach be used to deploy Virtools applications for debugging purposes only regardless or whether you chose the DEBUG or RELEASE configuration types.

Static Stand Alone Player “Single Bundled EXE File”

   After doing the previous compilation, it’s a good idea to get a single bundled EXE file, to do that, follow the following steps:
   1. Go to Solution Explorer, Right click, choose Properties, in the dialog window click on Configuration Manager and choose “ReleaseStatic”.
   2. Make sure you have the DirectX SDK installed – Only the October 2004 release will work, apparently, Microsoft newer releases of the SDK is not backward compatible with previous release, surprise surprise! - When you install the SDK, it’s a good idea to use a default installation; otherwise, you might have to change the configuration of the linked DLL’s from within the Solution Explorer Properties.
   3. You can skip this step- but I had to do it on my machine, apparently there were some missing DLL files for DirectX- open the file CustomPlayerStaticLibs.h, scroll down until you see the line:
   // virtools plugins
   Comment the following two lines:
   #pragma comment(lib,"3dsLoaderStatic")
   #pragma comment(lib,"XLoaderStatic")
   4. Build the solution, it might take a while, and unless configured in a different way, the output file will be “StaticPlayer.exe”, so when you try to run using the same steps as the previous compilation, remember to change the filename.
   The previous procedure compiles a single bundled EXE file for the Virtools player. The following is what might be considered the pros and cons of the compilation:
   • Pros:
   1. Ease of deployment.
   2. Securing the Virtools DLL files.
   • Cons:
   1. A deployed version might be tampered with; a batch file might be reconfigured to play a file with a parameter set other than the original one.
   2. The CMO/VMO file is still visible to the user.

Managing the Player, Modifying parameter passing

   To solve the problem of parameter passing, you can modify the code itself to allow for playing a Virtools file automatically without the need for parameters, this method is of course the preferred method of deployment regardless if you are compiling a static or a standalone player.
   To make your player play the file automatically, do the following steps:
   1. Open the file CustomPlayerApp.cpp.
   2. in the _ReadConfig Method , replace all the contents of the method with the following lines :
   ==============================
   const char* cmdLine = "-title test123 -width 800 -height 600";
   return _ReadCommandLine(cmdLine,oFilename);
   ==============================
   3. in the InitInstance method, replace the line :
   ==============================
   XString filename;
   ==============================
   With:
   ==============================
   XString filename="TEST123.cmo";
   ==============================
   4. Also in the InitInstance method, comment the following block of code:
   ==============================
   if(!_ReadConfig(filename,fileBuffer,fileSize)) {
   MessageBox(NULL,CANNOT_READ_CONFIG,
   INIT_ERROR,MB_OK|MB_ICONERROR)
   return FALSE;
   }
   ==============================
   And add the following line instead:
   ==============================
   _ReadConfig(filename,fileBuffer,fileSize);
   ==============================
   That should do it! Now you have a player that plays the file automatically without parameter passing, note that if you need to modify the parameters, you should do it in the first line mentioned in step 2, and you should it do it every time you need to change the parameters, since this compilation doesn’t read the command line parameters anymore even if you pass them, also the file name mentioned in step 3 in the second line should be changed according to the filename you are using.

Managing the Player, Embedding the Virtools File inside the player

   If you ever saw the HDRI demo produced by Virtools and you wanted to do something like it, then this section is for you, follow the following steps to the letter and you should be fine:
   1. Open the CustomPlayerApp.cpp file.
   2. in the init method , replace this block of code:
   ==============================
   XString filename;
   const char* fileBuffer = 0;
   XDWORD fileSize = 0;
   if(!_ReadConfig(filename,fileBuffer,fileSize)) {
   MessageBox(NULL,CANNOT_READ_CONFIG,
   INIT_ERROR,MB_OK|MB_ICONERROR);
   return FALSE;
   }
   ==============================
   With this one
   ==============================
   CString Type="VIRTOOLS";
   HRSRC rest=FindResource(NULL,
   MAKEINTRESOURCE(IDR_VIRTOOLS1),Type);
   HGLOBAL gl=LoadResource (NULL,rest);
   LPVOID lp=LockResource(gl);
   fileBuffer=(char*)lp;
   fileSize = SizeofResource (NULL,rest);
   _ReadConfig(filename,fileBuffer,fileSize);
   ==============================
   3. Go to Solution Explorer, right click on the Resource Files, choose
   Add >> Add Resource, click on Import, browse to your CMO or VMO file, and click Open, A dialog will appear requesting the Resource Type, Type VIRTOOLS and click ok.
   4. Rebuild solution.
   Now you have a player with an embedded VMO/CMO file, when you want to use this method for other files, make sure you delete the VIRTOOLS Resource from the Resource View and re-import the file, because this method stores the binary data of the VMO or the CMO in the solution, cached files will remain, also, this method seems to exhibit problems with large files with sizes that exceed 15 MB.