=====================
HOOPS AVI Integration
=====================

Using the AVI HIO Component
===========================

Audio Video Interleave, also known as AVI, is a multimedia container format introduced by Microsoft as part of its Video for Windows technology. AVI files can contain both audio and video data in a file container that allows synchronous audio-with-video playback. The AVI HIO component supports the export of AVI within HOOPS.

To use this integration, then follow the steps below to use the HOOPS/HIO component:

#. Create a *hio_plugins* directory in your application's working directory.  
#. Copy the *hio_avi.hio* file found in *<hoops>/bin/<platform>/hio_plugins/hio_avi* to the *hio_plugins* directory created in the previous step.
#. Run your application.

During startup, when HOOPS/MVO finds the AVI HIO component in your application's path, it will perform the following steps:  

#. Load in the necessary Video For Windows libraries. 
#. Create the appropriate output handlers.
#. Register both handlers and the associated file extensions to the ``HIOManager``.

Once the AVI HIO component is successfully loaded, your application will be able to export AVI files without having to recompile HOOPS. To utilize any further services available in the implementation of the AVI output handler, you must integrate directly the handler as described in :ref:`prog_guide/hio/HIO_AVIIntegration:Integrating directly with the AVI output handler`>.


Platform Support
----------------

Our integration is supported on all Microsoft Windows platforms.


Required Libraries
------------------

The AVI HIO component required the Video For Windows technology which is part of the Windows Platform SDK. 


Output Handler Options
======================

With the AVI HIO component, you can export animations created in HOOPS to a stand alone container that can be played on a wide variety of platforms. There some key output options that need to be set when exporting an animation to AVI. First, use the methods ``HOutputHandlerOptions::WindowWidth`` and ``HOutputHandlerOptions::WindowHeight`` to specify the dimensions of the resulting AVI file.  Then create an instance of AVIExportInfo. Within this structure, you can specify the start and end time for your animation via ``AVIExportInfo::starttick`` and ``AVIExportInfo::endtick``, respectively.  Finally, use the ``AVIExportInfo::resolution`` data member to specify how many milliseconds per frame.  Once you have populated this structure, set ``HOutputHandlerOptions::m_pExtendedData`` to point to it. The following sample code creates an AVI file whose dimensions are 320 x 240 and runs at 30 frames per second. 

Example::

	// Get a pointer to the AVI HOutputHandler object
	HOutputHandler *AVIOutput =  HIOManager::GetCurrentHIOManager()->GetOutputHandler("avi");       
	char *AVIName = "MyOutputAnimation.avi";

	// Setup the options structures
	// The m_width and m_height members of HOutputHandlerOptions() specify the width and height of the resulting AVI file. 
	// Additional parameters for the clip are in AVIExportInfo. They include the "starttick" of the animatiom, the "endtick" 
	// as well as the resolution of the video in frames per second.

	AVIExportInfo einfo;
	HOutputHandlerOptions options;
	options.m_Width  =  320;
	options.m_Height =  240;
	options.m_pHBaseView = m_pHView;
				
	einfo.starttick = 1;
	einfo.endtick = 500;
	einfo.resolution = 33;

	options.m_pExtendedData = &einfo;

	// Export the AVI file; the animation sequence will be automatically played back behind the scenes,
	// where each frame is rendered to an offscreen framebuffer via use of the HOOPS/3dGS Image Driver
	AVIOutput->FileOutputByKey(H_ASCII_TEXT(AVIName), -1, &options);
										

Rebuilding the HIO Component
============================

If you want to rebuild the AVI HIO component, simply open the *hio_avi_<version>.vcxproj* project located in the *<hoops>/Dev_Tools/hoops_hio/hio_avi/source*. Once the project is built, an *.hio* file will be created.


Integrating Directly with the AVI Output Handler
================================================

In this section, we will outline the steps involved in integrating your HOOPS-based application directly with the HOOPS implementation of the AVI output handler. First, ensure that you have the Windows Platform SDK installed on your system. Once all the binaries are installed in your path, please follow the steps below:

#. Add files *HIOUtilityAVI.h/.cpp** to your project. These files are located in the *Dev_Tools/hoops_hio/hio_avi/source* directory of your HOOPS installation. Refer to *hio_avi_<version>.vcxproj* in *Dev_Tools/hoops_hio/hio_avi/source* directory.
#. In your debug/release build, you should point to *vfw32.lib* which is the primary Video For Windows library. 

Once you have completed the above steps, you do not need to rely on the AVI HIO component anymore.  Please remove the associated HIO file from the *hio_plugins* directory in your application's working directory.  Note that in a direct integration, you must register ``HIOUtilityAVI`` as an output handler with the HIOManager so that the ``HBaseModel`` write functions can recognize that the AVI file format is supported.  For more information on HOOPS/MVO file input/output architecture, please see the section :doc:`File Input/Output and the I/O Manager </prog_guide/mvo/04_hio_manager>` of the HOOPS/MVO Programming Guide.

You should be able to export AVI files from your application with code similar to this:: 

	HIOUtilityAVI handler;

	// This code could be used to write a AVI file
	char *outputfile = "c:\\temp\\MyOutputAnimation.avi";
	HOutputHandlerOptions options;
	options.m_pHBaseView = m_pHView;

	HOutputHandlerOptions options;
	options.m_Width  =  320;
	options.m_Height =  240;
	options.m_pHBaseView = m_pHView;
				
	//Creating the AVI specific output handler data structure
	AVIExportInfo einfo;
	einfo.starttick = 1;
	einfo.endtick = 500;
	einfo.resolution = 33;
	
	//Pointing the output handler class to the AVI options structure  
	options.m_pExtendedData = &einfo;
	
	//Writing out the AVI file
	HFileOutputResult result = handler.FileOutputByKey(outputfile, m_pHView->GetModelKey(), &options);
