User Interface: Basic Graphics

The function ProWindowNameGet() returns the window name for the specified window identifier. The input parameter win_id is the identifier of the Creo Parametric window. The output parameter win_name is the name of the Creo Parametric window.

Resizing Windows

Functions Introduced:

ProWindowSizeGet()

ProGraphicWindowSizeGet()

ProWindowPixelOutlineGet()

ProWindowCoordinatePixelGet()

The function ProWindowSizeGet() returns the size of the Creo Parametric window including the User Interface border.

The function ProGraphicWindowSizeGet() returns the size of the Creo Parametric graphics window without the border. If the window occupies the whole screen. the window size is returned as 1. If the screen is 1024 pixels wide and the window is 512 pixels, the width will be returned as 0.5.

The function ProWindowPixelOutlineGet() returns the outline of the Creo Parametric window in pixels. The outline is the height and width of the graphic area.

The function ProWindowCoordinatePixelGet() converts the Windows coordinates received through the input argument point into Pixel coordinates. The input arguments are as follows:

•

window_id—Valid window identifier.

•

point—Window space 3D coordinates given by ProArray of the Pro3dPnt object.

The output argument pixelSpaceCoord is the 2D pixel coordinates in integers and is returned by a ProArray of the Pro2dPnt object.

Manipulating the Embedded Browser in Windows

Functions Introduced:

ProWindowBrowserSizeGet()

ProWindowBrowserSizeSet()

ProWindowURLShow()

ProWindowURLGet()

The functions ProWindowBrowserSizeGet() and ProWindowBrowserSizeSet() enable you to find and change size of the embedded browser in the Creo Parametric window. These functions refer to the browser size in terms of a percentage of the graphics window (0.0 to 100.0).

Note

The functions ProWindowBrowserSizeGet() and ProWindowBrowserSizeSet() are not supported if the browser is open in a separate window.

The functions ProWindowURLGet() and ProWindowURLShow() enable you to find and change the URL displayed in the embedded browser in the Creo Parametric window.

Repainting Windows

Functions Introduced:

The function ProWindowClear() temporarily removes all graphics from the specified window. If you give the function a window identifier of –1, it clears the current window.

This function is not equivalent to the Creo Parametric option to quit the window. It does not break the connection between the current solid and the window. That is the purpose of the function ProWindowDelete(), described later in this chapter.

The ProWindowRepaint() function is equivalent to the Creo Parametric command Repaint in the Graphics toolbar, and removes highlights. The function accepts –1 as the identifier, which indicates the current view.

The function ProWindowRefresh() is designed primarily for the purposes of animation. It updates the display very efficiently, but does not remove highlights. The function accepts –1 as the window identifier, which indicates the current window.

The function ProWindowRefit() performs exactly the same action as the Creo Parametric command View ▶ Refit . (It does not accept -1 as the current window. Use ProWindowCurrentGet() if you need the id of the current window.)

The function ProTreetoolRefresh() refreshes the display of the model tree for the specified model. This function is useful when you are modifying the model in some way, such as when you are creating patterns or features.

Controlling Which Window is Current

Functions Introduced:

ProWindowCurrentGet()

ProWindowCurrentSet()

ProAccessorywindowAboveactivewindowSet()

The functions ProWindowCurrentGet() and ProWindowCurrentSet() enable you to find out and change the current window. The window is active only for the purposes of the other Creo TOOLKIT commands that affect windows.

The function ProWindowCurrentSet() is not equivalent to the Creo Parametric command to activate the window and has no effect on the object returned by ProMdlCurrentGet().

The function ProAccessorywindowAboveactivewindowSet() allows you to display the accessory window always above the active Creo Parametric window, for the current Creo TOOLKIT application. Pass the input argument above_active_window as PRO_B_TRUE to display the accessory window on top of the current window. To remove this setting, pass the input argument above_active_window as PRO_B_FALSE.

Note

The configuration option accessory_window_above allows you to control the display of accessory window in Creo Parametric. The valid values are:

•

yes—Always displays the accessory window above the active window.

•

no—Does not display the accessory window above the active window. Here, whichever is the active window is displayed on top.

Creating and Removing Windows

Functions Introduced:

ProObjectwindowMdlnameCreate()

ProWindowDelete()

ProWindowCurrentClose()

ProAccessorywindowWithTreeMdlnameCreate()

The function ProObjectwindowMdlnameCreate() opens a new window containing a specified solid. The solid must already be in memory. If a window is already open on that solid, the function returns the identifier of that window. If the Main Window is empty, the function uses it instead of creating a new one. The section Graphics Colors and Line Styles shows how to use ProObjectwindowMdlnameCreate().

The function ProWindowDelete() closes a window and breaks the object-to-window attachment. The function deletes the window, if it is not the base window. You cannot break the attachment for the currently active window. Use the function ProWindowCurrentSet()to make a different window be the current window before calling this function.

The function ProWindowDelete() is the equivalent of the Creo Parametric command to quit the window. If the window is not the Main Window, it is also deleted from the screen.

To close the current window, use the function ProWindowCurrentClose(). When you call this function, the control must be returned to Creo Parametric to close the current window.

This function duplicates the behavior of the View ▶ Close command in Creo Parametric. If the current window is the original window created when Creo Parametric was started, the function clears the window; otherwise, the function removes the window from the screen.

Note

Any work done since the last save will be lost.

In Creo Parametric, when the main window is active, you can open an accessory window for operations such as edit an inserted component or a feature, preview an object, select a reference, and some other operations. The model tree associated with this Creo Parametric object is also displayed in the accessory window. For more information about the accessory window, refer the Creo Parametric help.

In Creo TOOLKIT , the function ProAccessorywindowWithTreeMdlnameCreate() opens an accessory window containing the specified object. If a window is already open with the specified object, the function returns the identifier of that window. If an empty window exists, the function uses that window to open the object. The input argument tree_flag controls the display of the model tree in the accessory window. If this flag is set to PRO_B_TRUE the model tree is displayed.

Retrieving the Owner of a Window

Function Introduced:

ProWindowMdlGet()

The function ProWindowMdlGet() retrieves the Creo Parametric model that owns the specified window. This function gives you details about the window needed to perform necessary actions on it.

Note

If no model is associated with the specified window, Creo TOOLKIT returns NULL as a model pointer and PRO_TK_NO_ERROR as a return value.

Visiting Windows

Function Introduced:

ProWindowsVisit()

The function ProWindowsVisit() enables you to visit all the Creo Parametric windows. For a detailed explanation of visiting functions, see the section Visit Functions in the Fundamentals chapter.

Activating Windows

Function Introduced:

ProWindowActivate()

The function ProWindowActivate() activates the specified window and sets it as the current window. When you call this function, the control must be returned to Creo Parametric to activate the specified window.

You can regain control by registering callback using the function ProUIDialogAppActionSet().

This functionality is equivalent to changing the active window by selecting and activating a window using the pull-down menu of Windows command under the View tab in Creo Parametric.

Note

This function works in asynchronous graphics mode only.

Solid Orientation

Functions Introduced:

ProWindowCurrentMatrixGet()

ProWindowPanZoomMatrixSet()

ProViewRefit()

Each graphics window in solid (Part or Assembly) mode has two transformation matrices associated with it—the view matrix and the window matrix. The view matrix describes the transformation between solid coordinates and screen coordinates. Therefore, the view matrix describes the orientation of the solid in the window.

The window matrix is the transformation between screen coordinates and window coordinates. The window matrix describes the pan and zoom factors. The screen coordinate at which a particular point on a solid is displayed is not affected by pans and zooms—this affects window coordinates only.

The view matrix is important because the mouse input functions and some of the graphics drawing functions use screen coordinates, while all solid geometry uses solid coordinates. The view matrix enables you to transform between the two systems. The function ProWindowCurrentMatrixGet() provides the window matrix for the current window.

The function ProWindowPanZoomMatrixSet() enables you to set the pan and zoom matrix (window matrix) for the current window.

The function ProViewRefit() zooms and pans the view to display the specified object in the window. The input arguments are:

•

model—Handle to the object. The supported object types are drawing, part, and assembly.

•

view—Handle to the view, which is used to display the object. If the object is a solid model, and is displayed in the current window, you can pass the argument as NULL.

If the object is a drawing, pass the handle to the background view. Use the function ProDrawingBackgroundViewGet() to get the handle to the background view.

Getting and Setting the View Matrix

The function ProViewMatrixGet() provides the view matrix for a specified window. Set the view argument to NULL for the current view.

The function ProViewMatrixSet() enables you to set the view matrix (if normalized), and therefore the orientation of the solid in the view.

Note

Function ProViewMatrixSet() does not cause the view to be repainted.

A 4x4 transformation matrix describes a shift and a scaling, as well as a reorientation. You set the view matrix to define a new orientation. Creo Parametric applies its own shift and scaling to the view matrix you provide to ensure that the solid fits properly into the view. This implies the following:

•

The matrix output by ProViewMatrixGet() is not the same as the one you previously input to the function ProViewMatrixSet(), although its orientation is the same.

•

Each row of the matrix you provide to ProViewMatrixSet() must have a length of 1.0, and the bottom row must be 0, 0, 0, 1.

•

The matrix you provide to ProViewMatrixSet() must be normalized—it cannot include scaling or shift. Example 1: Saving Three Views shows how to normalize a matrix.

Converting a Matrix to Orthonormal

Functions Introduced:

ProMatrixMakeOrthonormal()

The function ProMatrixMakeOrthonormal() converts a non-orthonormal matrix to an orthonormal matrix with the specified scaling factor.

The input arguments follow:

•

inMatrix—The matrix to be converted to orthonormal.

•

intended_scale—Scale factor to be applied on the matrix.

Storing Named Views

Functions Introduced:

ProViewStore()

ProViewRetrieve()

ProViewNamesGet()

ProViewFromModelitemGet()

ProViewNameLineGet()

ProViewIdFromNameLineGet()

ProViewNameSet()

ProViewDelete()

ProViewCreate()

The ProViewStore() and ProViewRetrieve() functions enable you to save and use a named view of the solid. They are equivalent to the Creo Parametric View ▶ Reorient commands Save, and Set in the Saved Views tab, under the Orientation dialog box. You can then select the view you want from the list of view names.

The function ProViewNamesGet() retrieves the names of the views in the specified solid.

The function ProViewFromModelitemGet() retrieves the view handle from a model item handle. The model item must be of type PRO_VIEW.

The function ProViewNameLineGet() retrieves the name of the view from the view handle.

The function ProViewIdFromNameLineGet() retrieves the ID of the view. The input arguments are:

•

model—Specifies the handle to the part or assembly associated with the drawing, or to the drawing that contains the view. This argument cannot be NULL.

•

view_name—Specifies the name of the view. This argument cannot be NULL.

The function ProViewNameSet() sets the name of the view in the specified solid. The inputs arguments are:

•

model—Specifies the handle to a part, assembly, or drawing. This argument cannot be NULL.

•

p_view—Specifies the handle of the view.

•

p_name—Specifies the name of the view.

The function ProViewDelete() deletes the view from the specified solid. The input arguments are:

•

model—Specifies the handle to a part, assembly, drawing. This argument cannot be NULL.

•

p_view—Specifies the handle of the view.

The function ProViewCreate() creates a new view or provides the specified name to an existing view. The input arguments are:

•

model—The handle to a part or assembly.

•

view_name—The name of the view that is created in the object database.

The output argument p_view is the handle to the view that is stored and is defined using the ProView object.

Example 1: Saving Three Views

The sample code in UgGraphViewsSave.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_graphics shows how to set the view matrix and store a named view.

Graphics Colors and Line Styles

Creo Parametric uses several predefined colors in its color map. The colors are represented by the values of ProColorType(), defined in the file ProToolkit.h. The names of the types generally indicate what they are used for in Creo Parametric, although many colormap entries are used for several different purposes. These also correspond to the system colors presented to the user through the user interface.

Note

PTC reserves the right to change both the definitions of the predefined colormap and also of the assignment of entities to members of the color map as required by improvements to the user interface. PTC recommends not relying on the predefined RGB color for displaying of Creo TOOLKIT entities or graphics, and also recommends against relying on the relationship between certain colormap entries and types of entities. The following section describe how to construct your application so that it does not rely on potentially variant properties in Creo Parametric.

Setting Colors to Desired Values

Functions Introduced:

ProTextColorModify()

ProGraphicsColorModify()

The functions ProTextColorModify() and ProGraphicsColorModify() enable you to select a different color to be used for either of the following:

•

Graphics text—User custom text drawn by the ProGraphicsTextDisplay. Graphics text is by default displayed using PRO_COLOR_LETTER.

•

Graphics—User custom graphics drawn by ProGraphics function, which is by default displayed using PRO_COLOR_DRAWING.

Both functions only affect the color used for new graphics, you draw using Creo TOOLKIT , not the colors used for items Creo Parametric draws.

Both functions take a ProColor structure as input. This structure allows you to specify color by one of the following three methods:

•

DEFAULT—use the default Creo Parametric color entry for new graphics or text.

•

TYPE—use a predefined ProColortype color.

•

RGB - use a custom RGB value. This method should be used for any graphics which should not be allowed to change color (for example; if an application wants a yellow line on the screen that should always be yellow and not depend on the chosen color scheme.

Both functions output the value of the previous setting. It is good practice to return the color to its previous value after having finished drawing an object.

Setting Colors to Match Existing Entities

Functions Introduced:

ProColorByTypeGet()

The functions ProGraphicsColorModify() and ProColorTextModify() allow you to draw graphics that will change color based on changes to the Creo Parametric colormap. This allows you to draw entities in similar colors to related entities created by Creo Parametric. However, if the associations between objects and colormap entries should change in a new release of Creo Parametric, the association between the application entities and the Creo Parametric entities would be lost. The function ProColorByTypeGet() returns the standard colormap entry corresponding to a particular entity in Creo Parametric. This allows applications to draw graphics that will always match the color of a particular Creo Parametric entity.

Example 2: Setting the Graphics Color to a Specific RGB Value

The sample code in UgGraphColorsAdjust.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_graphics shows how to set the graphics color to a specific RGB value.

Example 3: Setting The Graphics Color to Follow the Color of Creo Parametric Entity

The sample code in UgGraphColorsAdjust.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_graphics shows how to set the graphics color to follow the color of Creo Parametric Entity.

Modifying the Creo Parametric Color Map

Functions Introduced:

ProColormapGet()

ProColormapSet()

These functions enable you to find out and alter the color settings for Creo Parametric. Each color is defined in terms of the red, green, and blue values. The RGB values should be expressed in a range from 0.0 to 1.0. Note that some colors related to selection and highlighting are fixed and may not be modified.

Creo Parametric uses these colors for everything it displays.

Changes to the color map are preserved for the rest of the Creo Parametric session. If you want to have permanent changes, call ProColormapSet() in user_initialize().

Note

Changing the Creo Parametric color map can have unintended effects if the user has chosen an alternate color scheme. It may cause certain entries to blend into the background or to be confused with other types of entries.

Example 4: Modifying the Color of the HALF_TONE Display

The sample code in UgGraphColorsAdjust.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_graphics shows how to modify the default half-tone color (gray) to a brighter color, using the function ProColormapSet(). Creo Parametric uses half-tone color to display hidden lines.

Creo Parametric Color Schemes

Functions Introduced:

ProColormapAlternateschemeGet()

ProColormapAlternateschemeSet()

The functions ProColormapAlternateschemeGet() and ProColormapAlternateschemeSet() enable you to change the color scheme of Creo Parametric to a predefined color scheme by turning on and off the blended background (light to dark grey) for alternate schemes. The possible alternate color schemes are as follows:

•

PRO_COLORMAP_ALT_BLACK_ON_WHITE—Displays black entities shown on a white background.

•

PRO_COLORMAP_ALT_WHITE_ON_BLACK—Displays white entities shown on a black background.

•

PRO_COLORMAP_ALT_WHITE_ON_GREEN—Displays white entities shown on a dark green background.

•

PRO_COLORMAP_OPTIONAL1—Represents the color scheme with a dark background.

•

PRO_COLORMAP_OPTIONAL2—Represents the color scheme with a medium background.

•

PRO_COLORMAP_CLASSIC_WF—Resets the color scheme to the light to dark grey background (default upto Pro/ENGINEER Wildfire 4.0).

•

PRO_COLORMAP_ALT_DEFAULT—Resets the color scheme to the default color scheme of light to dark blue gradient background (from Pro/ENGINEER Wildfire 5.0 onwards).

Setting Line Styles for Creo Toolkit Graphics

Functions Introduced:

ProLinestyleSet()

ProLinestyleDataGet()

ProGraphicsModeSet()

The function ProLineStyleSet() enables you to set the style of graphics you draw. The function ProLinestyleDataGet()queries the definition of the line style.

The possible values for the line style are as follows:

•

PRO_LINESTYLE_SOLID—Solid line

•

PRO_LINESTYLE_DOT—Dotted line

•

PRO_LINESTYLE_CENTERLINE—Alternating long and short dashes

•

PRO_LINESTYLE_PHANTOM—Alternating long dashes and two dots

Displaying the Color Selection Dialog Box

Function Introduced:

ProUIColorSelectionShow()

The function ProUIColorSelectionShow() displays the dialog box used to select values for the red, green, blue (RGB) colors. The input arguments of this function are:

•

title – Specifies the title of the selection dialog box. If this argument is NULL, the default value RGB will be used.

•

default_rgb_color – Specifies the default RGB values that will be displayed when the dialog box is opened. The color black is selected, if the value specified for this argument is invalid.

To get the RGB value, you can use the following macros:

Macro	Value
#define PRO_UI_COLOR_RGB_FLAG	(1 << 24)
#define PRO_UI_COLOR_TRANSPARENT_RGB_FLAG	(1 << 25)
#define PRO_UI_COLOR_RGB(r,g,b)	(((r) & 0xff) \| (((g) & 0xff) << 8) \| (((b) & 0xff) << 16) \| PRO_UI_COLOR_RGB_FLAG)
#define PRO_UI_COLOR_TRANSPARENT_RGB(r,g,b)	(PRO_UI_COLOR_RGB (r, g, b) \| PRO_UI_COLOR_TRANSPARENT_RGB_FLAG)
#define PRO_UI_COLOR_IS_RGB(c)	((c) & PRO_UI_COLOR_RGB_FLAG ? PRO_B_TRUE : PRO_B_FALSE)
#define PRO_UI_COLOR_IS_TRANSPARENT_RGB(c)	((c) & PRO_UI_COLOR_TRANSPARENT_RGB_FLAG ? PRO_B_TRUE : PRO_B_FALSE)
#define PRO_UI_COLOR_RED_VALUE(c)	((c) & 0xff)
#define PRO_UI_COLOR_GREEN_VALUE(c)	(((c) >> 8) & 0xff)
#define PRO_UI_COLOR_BLUE_VALUE(c)	(((c) >> 16) & 0xff)
#define PRO_UI_COLOR_RGB_FLAGS(c)	(((c) >> 24) & 0xff)

Displaying Graphics

Functions Introduced:

ProGraphicsPenPosition()

ProGraphicsLineDraw()

ProGraphicsPolylineDraw()

ProGraphicsMultiPolylinesDraw()

ProGraphicsArcDraw()

ProGraphicsCircleDraw()

ProGraphicsPolygonDraw()

All the functions in this section draw graphics in the current window (the Creo Parametric current window, unless redefined by a call to ProWindowCurrentSet()), and use the color and line style set by calls to ProGraphicsColorSet() and ProLinestyleSet(). The functions draw the graphics in the Creo Parametric graphics color. The default graphics color is white.

By default, the graphics elements are not stored in the Creo Parametric display list, so they do not get redrawn by Creo Parametric when the user selects the Repaint command or the orientation commands in the Orientation group in the View tab. However, if you store graphics elements in either 2-D or 3-D display lists, Creo Parametric redraws them. See the section Display Lists for more information.

The functions ProGraphicsPenPosition() and ProGraphicsLineDraw() draw three-dimensional polylines in solid mode, and take solid coordinates.

The function ProGraphicsPenPosition() sets the point at which you want to start drawing the line. The function ProGraphicsLineDraw() draws a line to the given point from the position given in the last call to either of the two functions. You call ProGraphicsPenPosition() for the start of the polyline, and ProGraphicsLineDraw() for each vertex.

If you use these functions in Drawing mode they work correctly, but use screen coordinates instead of solid coordinates.

The ProGraphicsPolylineDraw() and ProGraphicsMultiPolylinesDraw() functions also draw polylines, but you need to have the whole polyline defined in a local array before you call either function. If you are drawing many lines, use ProGraphicsMultipolylinesDraw() to minimize the number of function calls.

The function ProGraphicsArcDraw() draws an arc, in screen coordinates.

The function ProGraphicsCircleDraw() uses solid coordinates for the center of the circle and the radius value, but draws the circle parallel to the plane of the window. You can position the circle at a chosen solid vertex, for example, and the circle will always be clearly visible as a circle, regardless of the current solid orientation.

Example 5: Displaying Lines and Circles

The sample code in UgGraphLineCircleDraw.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_graphics shows how to draws a circle at each point and draws lines between the points.

In this example, the user selects a series of points on a part surface.

Displaying Text

Function Introduced:

ProGraphicsTextDisplay()

The function ProGraphicsTextDisplay() places text, specified as a wide string, at a position specified in screen coordinates. Therefore, if you want to add text to a particular position on the solid, you must transform the solid coordinates into screen coordinates by using the view matrix.

Like the graphics polylines, arcs, and so on (added by the functions described in Displaying Graphics), the text items drawn by ProGraphicsTextDisplay() are not known to Creo Parametric, and therefore are not redrawn when you use the Repaint command. Use the notify or display list functions to tell Creo Parametric about the items.

Note

These points are in the coordinate system of the current object. If the current object is a part, the points must be in the coordinate system of the part. If the current object is an assembly, the points must be in the coordinate system of the assembly.

See the section Display Lists for more information on the display list functions. To add permanent text to a drawing (for example, a drawing note), see the section Drawings.

Controlling Text Attributes

Functions Introduced:

ProTextAttributesCurrentGet()

ProTextFontIdCurrentSet()

ProTextHeightCurrentSet()

ProTextRotationAngleCurrentSet()

ProTextSlantAngleCurrentSet()

ProTextWidthFactorCurrentSet()

These functions control the attributes of text added by calls to ProGraphicsTextDisplay(). You can get and set the following information:

•

The font identifier

•

The text height, in screen coordinates

•

The ratio of the width of each character (including the gap) as a proportion of the height

•

The angle of rotation of the whole text, in counterclockwise degrees

•

The angle of slant of the text, in clockwise degrees

Controlling Text Fonts

Functions Introduced:

ProTextFontDefaultIdGet()

ProTextFontNameGet()

ProTextFontNameToId()

ProTextFontRetrieve()

ProTextStyleFontGet()

ProTextStyleFontSet()

The function ProTextFontDefaultIdGet() returns the identifier of the default Creo Parametric text font.

The text fonts are identified in Creo Parametric by names, and in Creo TOOLKIT by integer identifiers. To move between the two types of font identifiers, use the functions ProTextFontNameGet() and ProTextFontNameToId(). Because the internal font identifiers could change between Creo Parametric sessions, it is important to call ProTextFontNameToId() each time you want to modify the font in Creo TOOLKIT.

The function ProTextFontRetrieve() loads a font with the specified name that can be used to display the text.

The functions ProTextStyleFontGet() and ProTextStyleFontSet() get and set the font used to display the text. The fonts are those available in the Font selector in the Text Style dialog in Creo Parametric.

Display Lists

Functions Introduced:

ProDisplist2dCreate()

ProDisplist2dDisplay()

ProDisplist2dDelete()

ProDisplist3dCreate()

ProDisplist3dDisplay()

ProDisplist3dDelete()

To generate the display of a solid in a window, Creo Parametric maintains two display lists. A display list contains a set of vectors used to represent the shape of the solid in the view.

The 3-D display list contains a set of three-dimensional vectors that represent an approximation to the geometry of the edges of the solid. It gets rebuilt every time the solid is regenerated.

The 2-D display list contains the two-dimensional projections of the 3-D display list onto the current window. It is rebuilt from the 3-D display list when the orientation of the solid changes.

The functions in this section enable you to add your own vectors to the display lists, so your own graphics will be redisplayed automatically by Creo Parametric, until the display lists are rebuilt.

For example, if you just use the functions described in Displaying Graphics, the items you draw remain on the screen only until the window is repainted. Furthermore, the objects are not plotted with the rest of the contents of the window because Creo Parametric does not know about them.

If, however, you add the same graphics items to the 2-D display list, they will survive each repaint (when zooming and panning, for example) and will be included in plots created by Creo Parametric.

If you add graphics to the 3-D display list, you get the further benefit that the graphics survive a change to the orientation of the solid and are displayed, even when you spin the solid dynamically.

To add graphics to a display list, you must write a function that displays the necessary vectors in three dimensions, using the graphics display functions in the usual way. For the 2-D display list, you call ProDisplist2dCreate() to tell Creo Parametric to use your function to create the display list vectors, then call ProDisplist2dDisplay() to ask it to display the new graphics those vectors represent.

Note

If you save the display information, you can reuse it in any session. The application should delete the display list data when it is no longer needed.

Using 3-D display lists is exactly analogous to using 2-D display lists.

Note that the function ProWindowRefresh() does not cause either of the display lists to be regenerated, but simply repaints the window using the 2-D display list.

The function ProSolidDisplay() regenerates both display lists, and therefore not only recenters the solid in the view and removes any highlights, but also removes any graphics you added using the 2-D display list functions.

Cosmetic Properties

You can enhance your model using Creo TOOLKIT functions that change the surface properties, or set different light sources. The following sections describe these functions in detail.

Surface Properties

Functions Introduced:

ProSurfaceSideAppearancepropsGet()

ProSurfaceSideAppearancepropsSet()

ProTexturePathGet()

ProSurfaceSideTextureplacementpropsGet()

ProSurfaceSideTextureplacementpropsSet()

ProSurfaceAppearanceDefaultPropsGet()

ProSurfaceSideTexturepropsGet()

ProSurfaceSideTexturepropsSet()

ProPartTessellate()

ProPartTessellationFree()

From Creo Parametric5.0.0.0 onwards, the following functions have been deprecated:

•

ProSurfaceAppearancepropsGet()

•

ProSurfaceAppearancepropsSet()

•

ProSurfaceTextureplacementpropsGet()

•

ProSurfaceTextureplacementpropsSet()

•

ProSurfaceTexturepropsGet()

•

ProSurfaceTexturepropsSet()

The functions described in this section enable you to retrieve and set the surface and texture properties for the first level models in the model hierarchy.

Use the functions ProSurfaceSideAppearancepropsGet() and ProSurfaceSideAppearancepropsSet() to retrieve and set the surface properties on a specified side of the surface for the specified element using the ProSurfaceAppearanceProps data structure.

The data structure is defined as follows:

typedef struct pro_surf_appearance_props
{
  double														                        ambient;
  double														                        diffuse;
  double														                        highlite;
  double														                        shininess;
  double														                        transparency;
  ProVector													                        color_rgb;
  ProVector													                        highlight_color;
  double														                        reflection;
  ProPath														                        name;
  ProPath														                        label;
  ProPath														                        description;
  ProPath														                       keywords;
} ProSurfaceAppearanceProps;

The ProSurfaceAppearanceProps data structure contains the following fields:

•

ambient—Specifies the indirect, scattered light the model receives from its surroundings. The valid range is 0.0 to 1.0.

•

diffuse—Specifies the reflected light that comes from directional, point, or spot lights. The valid range is 0.0 to 1.0.

•

highlite—Specifies the intensity of the light reflected from a highlighted surface area. The valid range is 0.0 to 1.0.

•

shininess—Specifies the properties of a highlighted surface area. A plastic model would have a lower shininess value, while a metallic model would have a higher value. The valid range is 0.0. to 1.0.

•

transparency—Specifies the transparency value, which is between 0 (completely opaque) and 1.0 (completely transparent).

•

color_rgb[3]—Specifies the color, in terms of red, green, and blue. The valid range is 0.0. to 1.0.

•

highlight_color—Specifies the highlight color, in terms of red, green, and blue. The valid range is 0.0 to 1.0.

•

reflection—Specifies how reflective the surface is. The valid range is 0 (dull) to 100 (shiny).

•

keywords—Mandatory field. Specifies how to set the texture on a model surface. If you do not want to set a value for this field, set a NULL string to it.

The input arguments to the function ProSurfaceSideAppearancepropsGet() are:

•

item—Specifies the ProModelitem object that represents the part, assembly component, subassembly, quilt, or surface.

•

surface_side—Specifies the direction of the side for the surface or quilt. Pass the value as 0 to specify the side which is along the surface normal. Pass 1 to specify the side opposite to the surface normal.

In cosmetic shade mode, Creo Parametric tessellates each surface by breaking it into a set of connected triangular planes. The function ProSurfaceTessellationGet() invokes this algorithm on a single specified surface and provides the coordinates of the triangle corners and the normal at each vertex. This function tessellates a single surface only.

You can use the function ProTexturePathGet() to retrieve the full path to the texture, decal, or bump map file.

Refer to the Tessellation Core: 3D Geometry for functions ProPartTessellate() and ProPartTessellationFree().

You can apply textures to the surfaces. Use the function ProSurfaceSideTexturepropsGet() to get the texture properties for the specified side of the surface. Use the function ProSurfaceSideTexturepropsSet() to set the surface texture properties for the specified side of the surface. Both these functions use the ProSurfaceTextureProps data structure to retrieve and set the surface texture properties.

The data structure is defined as follows:

typedef struct pro_surface_texture_props
{
  ProCharPath									                                       decal;
  ProCharPath									                                       texture_map;
  ProCharPath									                                       bump_map;
} ProSurfaceTextureProps;

The ProSurfaceTextureProps data structure contains the following fields:

•

decal—Specifies the full path to the texture map with the alpha channel (transparency). Otherwise, use NULL.

•

texture_map—Specifies the full path to the texture map.

•

bump_map—Specifies the full path to the bump map. A bump map enables you to create bumps on the surface of the texture map.

You can manipulate the placement of the surface textures. Use the function ProSurfaceSideTextureplacementpropsGet() to get the properties related to the placement of surface texture for the specified side of the surface. Use the function ProSurfaceSideTextureplacementpropsSet() to set the placement properties for the specified side of the surface texture. The functions ProSurfaceSideTextureplacementpropsGet() and ProSurfaceSideTextureplacementpropsSet() use the ProSurfaceTexturePlacementProps data structure.

The data structure is defined as follows:

typedef struct pro_surface_texture_placement_props
{

  ProTextureProjectionType			                                             projection;
  ProTextureType								                                             texture_type;
  ProLineEnvelope								                                             local_csys;
  double												                                             horizontal_offset;
  double												                                             vertical_offset;
  double												                                             rotate;
  double 												                                             horizontal_scale;
  double													                                           vertical_scale;
  double 													                                           bump_height;
  double													                                           decal_intensity;
  ProBoolean											                                           flip_horizontal;
  ProBoolean											                                           flip_vertical;
} ProSurfaceTexturePlacementProps;

The ProSurfaceTexturePlacementProps data structure contains the following fields:

•

projection—Specifies the projection type—planar, spherical, cylindrical, or box.

•

texture_type—Specifies the type of texture.

•

local_csys—Specifies the direction (for planar projection), or the whole coordinate system (which defines the center for the other projection types).

•

horizontal_offset and vertical_offset—Specifies the percentage of horizontal and vertical shift of the texture map on the surface.

•

rotate—Specifies the angle to rotate the texture map on the surface.

•

horizontal_scale and vertical_scale—Specifies the horizontal and vertical scaling of the texture map.

•

bump_height—Specifies the height of the bump on the surface of the texture map.

•

decal_intensity—Specifies the alpha or transparency mask intensity on the surface.

•

flip_horizontal and flip_vertical—Specifies that the texture map on the surface should be flipped horizontally or vertically.

Use the function ProSurfaceAppearanceDefaultPropsGet() to get the default appearance properties of the specified type of surface. The input argument appearance_type is specified by the enumerated data type ProDefaultAppearanceType. The output argument appearance_properties is specified by the data structure ProSurfaceAppearanceProps.

Setting Light Sources

Functions Introduced:

ProLightSourcesGet()

ProLightSourcesSet()

These functions retrieve and set the information associated with the specified window, respectively, using the ProLightInfo data structure. The data structure is defined as follows:

typedef struct pro_tk_light
{
   wchar_t												                                                         name[PRO_NAME_SIZE];
   ProLightType										                                                         type;
   ProBoolean											                                                         status;   /* active or inactive */
   double												                                                         rgb[3]; /* for all types */
   double												                                                         position[3]; /* for point and spot */
   double												                                                         direction[3]; /* for direction and spot */
   double												                                                         spread_angle; /* for spot, in radian */
   ProBoolean											                                                         cast_shadows;
} ProLightInfo;

The Pro_light structure contains the following fields:

•

name—Specifies the name of the light source.

•

type—Specifies the light type—ambient, direction, point, or spot.

•

status—Specifies whether the light source is active or inactive.

•

rgb—Specifies the red, green, and blue values, regardless of the light type.

•

position—Specifies the position of the light, for point and spot lights only.

•

direction—Specifies the direction of the light, for direction and spot lights only.

•

spread_angle—Specifies the angle the light is spread, for spot lights only.

•

cast_shadows—Specifies whether the light casts shadows. This applies to Creo Render Studio only. Refer to the Creo Render Studio Help for more information on Creo Render Studio.

Creating 3D Shaded Data for Rendering

The functions described in this section enable you to create 3D shaded data that can be attached to a scene and rendered in Creo Parametric.

Functions Introduced:

ProDispObjectCreate()

ProDispObjectAttach()

ProDispObjectDetach()

ProDispObjectDelete()

ProDispObjectSetTransform()

ProDispObjectSetSurfaceAppearanceProps()

The function ProDispObjectCreate()creates a display object. A display object collects user specified shaded triangle data. When you render an object in Creo Parametric, rendering is done based on the triangle data using lights and materials. The display object must be attached to the scene to be rendered. The object is always displayed in shaded mode irrespective of the display mode of the current view. No HLR operations are done on display objects. The input arguments are:

•

object_name—Specifies the name of the display object. The name must be unique.

•

flag—Specifies a bitmask that is used to set the property of the display object. The bitmask has the following bit flags:

○

0x0—This is the default value. No bit flag is passed. If no bit is set, the display object behaves like a solid.

○

PRO_DISP_OBJECT_TWO_SIDED—When this bit flag is set, the display object behaves like a quilt.

○

PRO_DISP_OBJECT_DYNAMIC_PREVIEW—When this bit flag is set, the display object is considered temporary which will be deleted and recreated frequently by the user application. When this flag is set, Creo Parametric will not store the data on graphics card.

•

num_strips—Specifies the number of triangle strips that will contain the triangle data.

•

strip_size—Specifies the number of vertices in each triangle strip. It is a ProArray of size num_strips.

•

strips_array—Specifies a ProArray of ProTriVertex structure. The structure contains information about the position and normals of the vertices for triangles.

The function ProDispObjectAttach() attaches the display object to a Creo Parametric scene.

After the object is attached, it will be rendered along with the Creo Parametric graphics. If the scene is regenerated, the Creo TOOLKIT application must reattach it. This API is supported only for 3D mode, that is, part, assembly, and so on and does not work in 2D mode, that is, drawings, sketch, layout, and so on. The input arguments are:

•

window—Specifies the ID of the window in which the display object must be attached to a Creo Parametric scene.

•

obj—Specifies the handle to the display object.

•

key_list—Specifies a ProArray which contains the member identifier table of the component to which the display object will be attached. Specify NULL if you want to attach the display object to the top level component.

•

new_key—Specifies the ID of the new node in the scene graph where the display object will be attached.

•

transform—Specifies the position of the display object relative to its parent as a ProMatrix object.

Use the function ProDispObjectDetach() to detach a display object from the Creo Parametric scene. The input arguments are:

•

window—Specifies the ID of the window from which the display object will be detached from a Creo Parametric scene.

•

key_list—Specifies a ProArray which contains the member identifier table of the display object ProDispObject which will be detached from the scene. Pass as input key_list along with new_key defined in the API ProDispObjectAttach().

The function ProDispObjectDelete() deletes the specified display object. You must detach the display object before deleting it.

The function ProDispObjectSetTransform() transforms a display object relative to its parent in the scene. Specify the new position using the ProMatrix object. It returns the original position of the display object as a ProMatrix object.

Use the function ProDispObjectSetSurfaceAppearanceProps() to set the display properties of the display object attached to a scene using the ProSurfaceAppearanceProps data structure. Refer to the section Surface Properties for more information on ProSurfaceAppearanceProps.

Example 1: Creating a Display Object

The sample code in TestDispObject.c located at <creo_toolkit_loadpoint>/protk_appls/pt_examples/pt_dispobj shows how to create a display object and attach it to a scene. It also shows how to set the display properties for the display object.