===========================
HOOPS/MFC Integration Guide
===========================

Introduction
============

This guide explains how to use the functionality provided by the HOOPS/MFC Classes.


Linking
=======

The HOOPS/MFC headers, export library, source code, and prebuilt release and debug DLLs are located in the */dev_tools/hoops_mfc* subdirectories. The */dev_tools/hoops_mfc/source* directory includes the Microsoft Developer Studio Project files to enable manual rebuilding on Windows.


Supported Platforms
===================

The HOOPS/MFC component has been tested and is supported on all the major Windows platforms.


Using HOOPS/MFC Libraries
=========================

Within the HOOPS installation, you will find several versions of HOOPS/MFC available. Each variety offers 
different features that developers might find useful as a foundation for their application. Note that each 
library has specific linking and distribution requirements. The following is a list of the available 
libraries found in the *<hoops>\\Dev_Tools\\hoops_mfc\\lib\\<platform>* directory:

* *hoops_mfcu.lib*: This library is Unicode compliant.
* *hoops_mfcu_sdi.lib*: This library is Unicode compliant and derived from the single document class.
* *hoops_mfcu_mgk.lib*: This Unicode compliant library links to the `Image Magick library <http://www.imagemagick.org/>`_ version of HOOPS/MVO, *hoops_mfcu_mgk.dll*.
* *hoops_mfcu_mgk_sdi.lib*: This Unicode compliant library is derived from the single document class. It also links to the `Image Magick library <http://www.imagemagick.org/>`_ version of HOOPS/MVO, *hoops_mfcu_mgk.dll*.
* *hoops_mfcu_mgk_dinput.lib*: This Unicode compliant library implements the Microsoft DirectX's DirectInput API for capturing events on a :ref:`3D Mouse/Joystick available in HOOPS/MVO <prog_guide/mvo/12_event_handling:3D Mouse and joystick events>`. If you choose to use this library, your application must also ship with Microsoft DirectX.

For developers with applications that do not use Unicode, the HOOPS/MFC library must be rebuilt manually with the correct preprocessor directives.


Printing and Print Preview
==========================
        
The ``CHoopsView`` object supports native Windows printing and print-preview, by providing a HOOPS/MFC-specific implementation of the ``CView::OnPrint`` virtual function. The associated ``HBaseView`` scene will be sent to the printer. Refer to the :ref:`HOOPS/MVO startup segment structure <tech_overview/mvo_technical_overview:HOOPS/MVO and HOOPS/3DGS>`.

The following ``CHoopsView`` class members provide additional HOOPS/MFC-specific control of the underlying printing logic::

	m_bFastPrint; // flag enabling print optimization; if set
                  // HOOPS will print using software-frame-buffer logic
				 
	m_bMetaPrint; // flag enabling creation and playing of a metafile to
                  // the printer

If you needed to perform additional application-specific logic within the ``CHoopsView::OnPrint`` method, you could implement the function in your app-specific CHoopsView class, and call the base class, ``CHoopsView::OnPrint``, to perform the HOOPS-specific printing.


Passing in Custom Output Options
================================

The HOOPS/MFC-specific ``OnPrint`` logic is based on HOOPS/MVO output support, and therefore utilizes an overloaded version of the ``HOutputHandlerOptions`` class, called ``GDIExportInformation``. This structure can be customized by modifying the ``CPrintInfo`` data as follows::

	void MyCustomHoopsView::OnPrint(CDC* pDC, CPrintInfo* pInfo) 
	{
		GDIExportInformation options; 
		// setup customizations to GDIExportInformation here
		
		// pass our custom options into CPrintInfo
		pInfo->m_lpUserData = &options;
		
		CHoopsView::OnPrint(pDC, pInfo);
	}


Print to Scale
==============

HOOPS/MVO output supports 'output to scale'. See :ref:`this section <prog_guide/mvo/04_hio_manager:Printing to hardcopy>` of the HOOPS/MVO Programming Guide for more info. The following example shows how we could print the scene with a specific scaling factor::

	void MyCustomHoopsView::OnPrint(CDC* pDC, CPrintInfo* pInfo) 
	{
		GDIExportInformation options;
		
		options.PrintToScale(1.0f);      // as an example, let's set the scaling factor to indicate that 1 world-space-unit equals 1cm
		pInfo->m_lpUserData = &options;
		
		CHoopsView::OnPrint(pDC, pInfo);
	}


Raster Output Options
=====================

Generating raster output can require high memory footprint, particular on larger format devices. The following members of ``GDIExportInformation`` allow the developer to control how the raster output is generated:

* ``GDIExportInfo::bConserveMemory``
* ``GDIExportInfo::image_dpi``

If you wish to modify these values (rather than use the defaults), pass in a customer version of the ``GDIExportInformation`` structure into ``CHoopsView::OnPrint`` as follows::

	void MyCustomHoopsView::OnPrint(CDC* pDC, CPrintInfo* pInfo) 
	{
		GDIExportInformation options;
		
		options.bConserveMemory = true;     // instruct the printer to perform banding
		options.image_dpi = 300;            // render the rasterized portion at 300 dpi to produce a high-quality result
		pInfo->m_lpUserData = &options;
		
		CHoopsView::OnPrint(pDC, pInfo);
	}


Copy to Clipboard
=================

The ``CHoopsView`` object supports Windows "Copy to Clipboard" by providing a HOOPS/MFC-specific implementation of the ``CView::OnEditCopy`` message map function. Similar to ``CHoopsView::OnPrint``, the ``CHoopsView::OnEditCopy`` function will copy the associated ``HBaseView`` scene to the clipboard.

The following ``CHoopsView`` class members provide for control of the underlying clipboard logic::

	m_bClipboardTruecolor;    // flag enabling clipboard true color support
			
	m_MetafileType;           // selects metafile type; can be WMF or EMF

If you needed to perform additional application-specific logic within the handling of the ``CHoopsView::OnEditCopy`` message, you could add this function to the message-map of your app-specific ``CHoopsView`` class, and call the base class, ``CHoopsView::OnEditCopy`` to perform the HOOPS-specific "Copy to Clipboard". 


Sharing Palettes
================

Windows palette management becomes a concern when using the HOOPS Visualize MSW driver for display on 8-bit systems, which should be quite rare considering that all computer displays support 24-bit or higher color.

Nonetheless, the HOOPS/MFC classes provide support for creating a Windows palette and sharing it among multiple ``CHoopsView`` objects, in order to support 8-bit color mode when using the MSW driver. Creation of the shareable palette is enabled by default, but the palette needs to be accessed and passed into each HOOPS/MVO View object during it's creation.

The shared palette is accessed via the ``CHoopsView::GetPalette`` function, and passed into HOOPS Visualize via the ``HBaseView`` object's constructor. The following code is used in the ``CMyHoopsView`` constructor to pass the shared palette to Visualize::
		  
	m_pHView = new HMyBaseView(hmodel, NULL, NULL, NULL, (long) m_hWnd, (long)(HPALETTE)*(GetPalette()));
