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 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 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 3D Mouse/Joystick available in HOOPS/MVO. 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 HOOPS/MVO startup segment structure.

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 this section 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”.