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<hoops version>_vc<MS Visual Studio version>.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<hoops version>_vc<MS Visual Studio version>.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".

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()));
top_level:4 api_ref/additional_resources:1