Hardcopy

class Hardcopy

The Hardcopy class attempts to reproduce the scene graph to each of its supported export types. This includes printing to physical paper and 2D PDF.

Default values for the various fields of the Hardcopy class can be found here.

Public Types

enum class BackgroundPreference : uint32_t

The Hardcopy::BackgroundPreference class is used to decide what the Hardcopy background looks like.

Values:

enumerator UseBackgroundColor

The current scene background is exported to Hardcopy.

enumerator ForceSolidWhite

The exported Hardcopy background will be white.

enum class PDFFontPreference : uint32_t

The Hardcopy::PDFFontPreference class is used to decide how fonts are treated during PDF exports

Values:

enumerator DoNotEmbedFonts

Fonts used are not embedded in exported PDF files. The resulting file will only look correct when opened on platforms which have the fonts used in the PDF document installed

enumerator EmbedFonts

Fonts used in the PDF are embedded into it. The exported PDF file will render the same way on any platform. Its size will be larger than if fonts were not embedded.

enum class RenderingAlgorithm : uint32_t

The Hardcopy::RenderingOptions class is used to decide how the Hardcopy export will be conducted.

Values:

enumerator TwoPassPrint

The default Hardcopy export. Two passes are used to ensure that vector data is as detailed as possible, while saving on file size by rendering non-vector data at lower resolution.

enumerator SinglePassPrint

The Hardcopy export completes in a single pass. Non-vector data may take up large amount of space on disk. If your on-screen scene was rendered using the Priority HSRA, using SinglePassPrint is required in order for the Hardcopy export to be accurate.

enum class ResolutionUnits : uint32_t

The Hardcopy::Resolution class is a concept class for hardcopy output-resolution-related enum classes.

Values:

enumerator DPCM

Dots Per Centimeter.

enumerator DPI

Dots Per Inch.

enumerator DotsPerCentimeter

Dots Per Centimeter.

enumerator DotsPerInch

Dots Per Inch.

enum class SizeUnits : uint32_t

The Hardcopy::Size class is a concept class for hardcopy output-size-related enum classes.

Values:

enumerator Centimeters

Centimeters.

enumerator Inches

Inches.

class File

Encapsulates all the functions and options related to exporting HPS::Hardcopy files.

Public Types

enum class Driver : uint32_t

The Driver indicates whether the hardcopy will be exported as PDF or Postscript

Values:

enumerator PDF
enumerator Postscript

Public Static Functions

static IOResult Export(char const *in_filename, Driver in_driver_type, HPS::WindowKey const &in_window, ExportOptionsKit const &in_options)

Export to a PDF or Postscript file

Parameters:

  • in_filename – The name of the output file to export

  • in_driver_type – The hardcopy driver to use.

  • in_window – The window to print.

  • in_options – Export options such as resolution, size and wysiwyg.

class ExportOptionsKit : public HPS::Kit

The HPS::Hardcopy::File::ExportOptionsKit class contains settings controlling hardcopy export. Calling HPS::Hardcopy::File::ExportOptionsKit::GetDefault() will return an options kit with values found in here.

Public Functions

virtual bool Empty() const

Indicates whether this ExportOptionsKit has any values set on it.

Returns:

true if no values are set on this ExportOptionsKit, false otherwise.

bool Equals(ExportOptionsKit const &in_kit) const

Check if the source ExportOptionsKit is equivalent to this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to compare to this ExportOptionsKit.

Returns:

true if the objects are equivalent, false otherwise.

ExportOptionsKit()

The default constructor creates an empty ExportOptionsKit object.

ExportOptionsKit(ExportOptionsKit &&in_that)

The move constructor creates an ExportOptionsKit by transferring the underlying impl of the rvalue reference to this ExportOptionsKit thereby avoiding a copy and allocation.

Parameters:

in_that – An rvalue reference to an ExportOptionsKit to take the impl from.

ExportOptionsKit(ExportOptionsKit const &in_kit)

The copy constructor creates a new ExportOptionsKit object that contains the same settings as the source ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to copy.

inline virtual HPS::Type ObjectType() const

This function returns the type the object, as declared (if the object is derived, this does not give the true type of the derived object).

Returns:

The declared type of the object in question, which may differ from the true, underlying type.

bool operator!=(ExportOptionsKit const &in_kit) const

Check if the source ExportOptionsKit is not equivalent to this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to compare to this ExportOptionsKit.

Returns:

true if the objects are not equivalent, false otherwise.

ExportOptionsKit &operator=(ExportOptionsKit &&in_that)

The move assignment operator transfers the underlying impl of the rvalue reference to this ExportOptionsKit thereby avoiding a copy.

Parameters:

in_that – An rvalue reference to an ExportOptionsKit to take the impl from.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &operator=(ExportOptionsKit const &in_kit)

Copies the source ExportOptionsKit into this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to copy.

Returns:

A reference to this ExportOptionsKit.

bool operator==(ExportOptionsKit const &in_kit) const

Check if the source ExportOptionsKit is equivalent to this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to compare to this ExportOptionsKit.

Returns:

true if the objects are equivalent, false otherwise.

void Set(ExportOptionsKit const &in_kit)

Copies the source ExportOptionsKit into this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to copy.

ExportOptionsKit &SetBackgroundPreference(Hardcopy::BackgroundPreference in_background_preference)

The background preference setting is used to decide how the background of this Hardcopy operation will be handled. If no preference is specified, the background will be forced to be white.

Parameters:

in_background_preference – how the background for this Hardcopy export will be handled.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetHiddenLineSorting(bool in_on, float in_activation_weight = 2.0f, HPS::Line::SizeUnits in_units = HPS::Line::SizeUnits::Pixels)

Species whether hidden lines are sorted, and if so, what the threshold for sorting is. If Hidden Line Sorting is activated, lines will be printed in proper z-order. If this option is not activated, the order in which lines are printed is non-deterministic. Enabling this option will result in slower performance.

Parameters:

  • in_on – Whether to sort hidden lines or not.

  • in_activation_weight – What is the minimum size of hidden lines that are sorted. Lines thinner than this will not be sorted.

  • in_units – Units applied to in_activation_weight.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetPDFFontPreference(Hardcopy::PDFFontPreference in_pdf_font_preference)

The PDF font preference setting is used to decide whether fonts will be embedded in an expored PDF file. If no preference is specified, fonts will not be embedded in the exported PDF file. Embedding fonts makes sure that text included in exported PDF files will render the same way on any platform, but has the side effect of increasing the size of exported PDF. The 14 default PDF fonts are never embedded, regardless of this setting, since they are guaranteed to be available to conforming PDF readers.

Parameters:

in_pdf_font_preference – the PDF font preference for this Hardcopy export

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetRenderingAlgorithm(Hardcopy::RenderingAlgorithm in_rendering_algorithm)

The rendering algorithm setting is used to decide how the Hardcopy export will be performed. If no preference is specified, two passes will be used for the Hardcopy export.

Parameters:

in_rendering_algorithm – how the Hardcopy export will be handled.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetResolution(float in_resolution, Hardcopy::ResolutionUnits in_units = Hardcopy::ResolutionUnits::DPI)

Sets the resolution of the image to be inserted into the Hardcopy.

See also

Default value

Parameters:

  • in_resolution – Resolution (dots per inch or dots per centimeter).

  • in_units – Units of preceding arguments. Defaults to Inches.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetScale(float in_scale, Hardcopy::SizeUnits in_units = Hardcopy::SizeUnits::Inches)

Scales Visualize units to correspond to real world units. For example, SetScale(1.0f, Hardcopy::SizeUnits::Inches), will make it so that every Visualize unit corresponds to 1 inch for this export, SetScale(2.0f, Hardcopy::SizeUnits::Centimeters), will make it so that every Visualize unit corresponds to 2 centimeters for this export. SetScale(0.2, Hardcopy::SizeUnits::Centimeters), will make it so that every Visualize unit corresponds to 2 millimeters for this export. Setting a scale is not defined for perspective cameras.

Parameters:

  • in_scale – the unit scale. in_scale is required to be a positive number.

  • in_units – the unit in_scale is expressed in.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetSize(float in_width, float in_height, Hardcopy::SizeUnits in_units = Hardcopy::SizeUnits::Inches)

Sets the size of the image to be inserted into the Hardcopy.

See also

Default value

Parameters:

  • in_width – Width in inches.

  • in_height – Height in inches.

  • in_units – Units of preceding arguments. Defaults to Inches

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetWYSIWYG(bool in_onoff)

Enables or disables WYSIWYG hardcopy output. The WYSIWYG setting (which stands for What You See Is What You Get) works as follows:

  • If true, what you see on the screen is what will be printed. This is the default.

  • If false, everything which will fit on the page size you have specified will be printed, even if some of that is not on screen when you issue the command.

See also

Default value

Parameters:

in_onoff – true is on, false is off.

Returns:

A reference to this ExportOptionsKit.

void Show(ExportOptionsKit &out_kit) const

Copies this ExportOptionsKit into the given ExportOptionsKit.

Parameters:

out_kit – The ExportOptionsKit to populate with the contents of this ExportOptionsKit.

bool ShowBackgroundPreference(Hardcopy::BackgroundPreference &out_background_preference) const

Shows the background preference for this Hardcopy export.

Parameters:

out_background_preference – the preference for the background of this Hardcopy export.

Returns:

true if a background preference setting was specified, false otherwise.

bool ShowHiddenLineSorting(bool &out_state, float &out_threshold, HPS::Line::SizeUnits &out_units) const

Shows the hidden line sorting options of Hardcopy.

Parameters:

  • out_state – Whether hidden line sorting is on or off.

  • out_threshold – The minimum width at which hidden lines are sorted.

  • out_units – The units that out_threshold is measured in.

Returns:

true if the setting is valid, false otherwise.

bool ShowPDFFontPreference(Hardcopy::PDFFontPreference &out_pdf_font_preference) const

Shows the PDF font preference for this Hardcopy export.

Parameters:

out_pdf_font_preference – the PDF font preference of this Hardcopy export.

Returns:

true if a PDF font preference was specified, false otherwise.

bool ShowRenderingAlgorithm(Hardcopy::RenderingAlgorithm &out_rendering_algorithm) const

Shows the rendering algorithm for this Hardcopy export.

Parameters:

out_rendering_algorithm – the rendering algorithm setting of this Hardcopy export.

Returns:

true if a rendering algorithm setting was specified, false otherwise.

bool ShowResolution(float &out_resolution, Hardcopy::ResolutionUnits &out_units) const

Shows the resolution of the image to be inserted into the Hardcopy.

Parameters:

  • out_resolution – Resolution (dots per inch or dots per centimeter).

  • out_units – Units of preceding arguments.

Returns:

true if a size setting was specified, false otherwise.

bool ShowScale(float &out_scale, HPS::Hardcopy::SizeUnits &out_units) const

Shows true if a scale has been set

Parameters:

  • out_scale – the scale specified.

  • out_units – the units out_scale is specified in.

Returns:

true if a scale setting was specified, false otherwise.

bool ShowSize(float &out_width, float &out_height, Hardcopy::SizeUnits &out_units) const

Shows the size of the image to be inserted into the Hardcopy.

Parameters:

  • out_width – Width.

  • out_height – Height.

  • out_units – Units of preceding arguments.

Returns:

true if a size setting was specified, false otherwise.

bool ShowWYSIWYG(bool &out_onoff) const

Shows true if wysiwyg has been enabled

Parameters:

out_onoff – whether ‘what you see is what you get’ is turned on or off

Returns:

true if a wysiwyg setting was specified, false otherwise.

ExportOptionsKit &UnsetBackgroundPreference()

Removes the background preference setting from this Hardcopy export.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetEverything()

Removes all settings from this ExportOptionsKit.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetHiddenLineSorting()

Removes the line sorting settings for hidden lines from Hardcopy

Returns:

A reference to this object.

ExportOptionsKit &UnsetPDFFontPreference()

Removes the PDF font preference setting from this Hardcopy export.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetRenderingAlgorithm()

Removes the rendering algorithm setting from this Hardcopy export.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetResolution()

Removes the resolution of the image to be inserted into the Hardcopy.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetScale()

Removes the scale setting from Hardcopy.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetSize()

Removes the size of the image to be inserted into the Hardcopy.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetWYSIWYG()

Removes the wysiwyg setting from Hardcopy.

Returns:

A reference to this ExportOptionsKit.

virtual ~ExportOptionsKit()

Public Static Functions

static ExportOptionsKit GetDefault()

Creates a ExportOptionsKit which contains the default settings. The returned object will not necessarily have values set for every option, but it will have settings for those options where it is reasonable to have a default.

Returns:

A ExportOptionsKit with the default settings.

Public Static Attributes

static const HPS::Type staticType = HPS::Type::HardcopyExportOptionsKit
class GDI

Public Static Functions

static IOResult Export(intptr_t in_hdc, intptr_t in_attribdc, HPS::WindowKey const &in_window, ExportOptionsKit const &in_options)

Export to a printer HDC

Parameters:

  • in_hdc – The handle to the output device context.

  • in_attribdc – The handle to the output attribute device context.

  • in_window – The window to print

  • in_options – Options for performing the export

static IOResult ExportClipboard(HPS::WindowKey const &in_window, ExportOptionsKit const &in_options)

Export to the Clipboard.

Parameters:

  • in_window – The window to export

  • in_options – Options for performing the export

static IOResult ExportEMF(char const *in_filename, WindowKey const &in_window, ExportOptionsKit const &in_options)

Export to an Enhanced MetaFile.

Parameters:

  • in_filename – The name of the file to export

  • in_window – The window to export

  • in_options – Options for performing the export

class ExportOptionsKit : public HPS::Kit

The ExportOptionsKit class contains settings controlling hardcopy export.

Public Functions

virtual bool Empty() const

Indicates whether this ExportOptionsKit has any values set on it.

Returns:

true if no values are set on this ExportOptionsKit, false otherwise.

bool Equals(ExportOptionsKit const &in_kit) const

Check if the source ExportOptionsKit is equivalent to this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to compare to this ExportOptionsKit.

Returns:

true if the objects are equivalent, false otherwise.

ExportOptionsKit()

The default constructor creates an empty ExportOptionsKit object.

ExportOptionsKit(ExportOptionsKit &&in_that)

The move constructor creates an ExportOptionsKit by transferring the underlying impl of the rvalue reference to this ExportOptionsKit thereby avoiding a copy and allocation.

Parameters:

in_that – An rvalue reference to an ExportOptionsKit to take the impl from.

ExportOptionsKit(ExportOptionsKit const &in_kit)

The copy constructor creates a new ExportOptionsKit object that contains the same settings as the source ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to copy.

inline virtual HPS::Type ObjectType() const

This function returns the type the object, as declared (if the object is derived, this does not give the true type of the derived object).

Returns:

The declared type of the object in question, which may differ from the true, underlying type.

bool operator!=(ExportOptionsKit const &in_kit) const

Check if the source ExportOptionsKit is not equivalent to this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to compare to this ExportOptionsKit.

Returns:

true if the objects are not equivalent, false otherwise.

ExportOptionsKit &operator=(ExportOptionsKit &&in_that)

The move assignment operator transfers the underlying impl of the rvalue reference to this ExportOptionsKit thereby avoiding a copy.

Parameters:

in_that – An rvalue reference to an ExportOptionsKit to take the impl from.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &operator=(ExportOptionsKit const &in_kit)

Copies the source ExportOptionsKit into this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to copy.

Returns:

A reference to this ExportOptionsKit.

bool operator==(ExportOptionsKit const &in_kit) const

Check if the source ExportOptionsKit is equivalent to this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to compare to this ExportOptionsKit.

Returns:

true if the objects are equivalent, false otherwise.

void Set(ExportOptionsKit const &in_kit)

Copies the source ExportOptionsKit into this ExportOptionsKit.

Parameters:

in_kit – The source ExportOptionsKit to copy.

ExportOptionsKit &SetBackgroundPreference(Hardcopy::BackgroundPreference in_background_preference)

The background preference setting is used to decide how the background of this Hardcopy operation will be handled. If no preference is specified, the background will be forced to be white.

Parameters:

in_background_preference – how the background for this Hardcopy export will be handled.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetHiddenLineSorting(bool in_on, float in_activation_weight = 2.0f, HPS::Line::SizeUnits in_units = HPS::Line::SizeUnits::Pixels)

Species whether hidden lines are sorted, and if so, what the threshold for sorting is. If Hidden Line Sorting is activated, lines will be printed in proper z-order. If this option is not activated, the order in which lines are printed is non-deterministic. Enabling this option will result in slower performance.

Parameters:

  • in_on – Whether to sort hidden lines or not.

  • in_activation_weight – What is the minimum size of hidden lines that are sorted. Lines thinner than this will not be sorted.

  • in_units – Units applied to in_activation_weight.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetRenderingAlgorithm(Hardcopy::RenderingAlgorithm in_rendering_algorithm)

The rendering algorithm setting is used to decide how the Hardcopy export will be performed. If no preference is specified, two passes will be used for the Hardcopy export.

Parameters:

in_rendering_algorithm – how the Hardcopy export will be handled.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetResolution(float in_resolution)

Sets the resolution of the image to be inserted into the Hardcopy.

Parameters:

in_resolution – Resolution in DPI (dots per unit).

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetScale(float in_scale, Hardcopy::SizeUnits in_units = Hardcopy::SizeUnits::Inches)

Scales Visualize units to correspond to real world units. For example, SetScale(1.0f, Hardcopy::SizeUnits::Inches), will make it so that every Visualize unit corresponds to 1 inch for this export, SetScale(2.0f, Hardcopy::SizeUnits::Centimeters), will make it so that every Visualize unit corresponds to 2 centimeters for this export. SetScale(0.2, Hardcopy::SizeUnits::Centimeters), will make it so that every Visualize unit corresponds to 2 millimeters for this export. Setting a scale is not defined for perspective cameras.

Parameters:

  • in_scale – the unit scale. in_scale is required to be a positive number.

  • in_units – the unit in_scale is expressed in.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetSize(float in_width, float in_height)

Sets the size of the image to be exported to the Clipboard or EMF file. This value is ignored for printer export.

Parameters:

  • in_width – Width in inches.

  • in_height – Height in inches.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &SetWYSIWYG(bool in_onoff)

Enables or disables wysiwyg hardcopy output

Parameters:

onoff – true is on, false is off

Returns:

A reference to this ExportOptionsKit.

void Show(ExportOptionsKit &out_kit) const

Copies this ExportOptionsKit into the given ExportOptionsKit.

Parameters:

out_kit – The ExportOptionsKit to populate with the contents of this ExportOptionsKit.

bool ShowBackgroundPreference(Hardcopy::BackgroundPreference &out_background_preference) const

Shows the background preference for this Hardcopy export.

Parameters:

out_background_preference – the preference for the background of this Hardcopy export.

Returns:

true if a background preference setting was specified, false otherwise.

bool ShowHiddenLineSorting(bool &out_state, float &out_threshold, HPS::Line::SizeUnits &out_units) const

Shows the hidden line sorting options of Hardcopy.

Parameters:

  • out_state – Whether hidden line sorting is on or off.

  • out_threshold – The minimum width at which hidden lines are sorted.

  • out_units – The units that out_threshold is measured in.

Returns:

true if the setting is valid, false otherwise.

bool ShowRenderingAlgorithm(Hardcopy::RenderingAlgorithm &out_rendering_algorithm) const

Shows the rendering algorithm for this Hardcopy export.

Parameters:

out_rendering_algorithm – the rendering algorithm setting of this Hardcopy export.

Returns:

true if a rendering algorithm setting was specified, false otherwise.

bool ShowResolution(float &out_resolution) const

Shows the resolution of the image to be inserted into the Hardcopy.

Parameters:

out_resolution – Resolution in specified units (dots per unit).

Returns:

true if a size setting was specified, false otherwise.

bool ShowScale(float &out_scale, HPS::Hardcopy::SizeUnits &out_units) const

Shows true if a scale has been set

Parameters:

  • out_scale – the scale specified.

  • out_units – the units out_scale is specified in.

Returns:

true if a scale setting was specified, false otherwise.

bool ShowSize(float &out_width, float &out_height) const

Shows the size of the image to be exported to the Clipboard or EMF file. This value is ignored for printer export.

Parameters:

  • out_width – Width in inches.

  • out_height – Height in inches.

Returns:

true if a size setting was specified, false otherwise.

bool ShowWYSIWYG(bool &out_onoff) const

Shows true if wysiwyg has been enabled

Returns:

true if a size setting was specified, false otherwise.

ExportOptionsKit &UnsetBackgroundPreference()

Removes the background preference setting from this Hardcopy export.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetEverything()

Removes all settings from this ExportOptionsKit.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetHiddenLineSorting()

Removes the line sorting settings for hidden lines from Hardcopy

Returns:

A reference to this object.

ExportOptionsKit &UnsetRenderingAlgorithm()

Removes the rendering algorithm setting from this Hardcopy export.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetResolution()

Removes the resolution of the image to be inserted into the Hardcopy.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetScale()

Removes the scale setting from Hardcopy.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetSize()

Removes the size of the image to be inserted into the Hardcopy.

Returns:

A reference to this ExportOptionsKit.

ExportOptionsKit &UnsetWYSIWYG()

Removes the wysiwyg setting from Hardcopy.

Returns:

A reference to this ExportOptionsKit.

virtual ~ExportOptionsKit()

Public Static Attributes

static const HPS::Type staticType = HPS::Type::HardcopyGDIExportOptionsKit