Pen Table Priority and Troubleshooting Priority Problems

(This article applies to MicroStation and later.) 

One of the most significant new features in the MicroStation V8 XM Edition was the introduction of a true 3D graphics display system. This allowed intersecting and overlapping 3D geometry to be displayed and printed accurately, rather than relying on the file order of elements. Unfortunately, this innovation dealt a major blow to the pen table application's priority feature, which until the V8 XM Edition relied on that file order display.

With the graphics system sorting elements by their Z coordinates (and 2D elements are simply treated as 3D elements with Z=0), the pen table application's method of deferring prioritized elements to the end of the print job, then reprocessing them in priority order, wouldn't work. The pen table could rearrange the element order all day long, and it wouldn't make a bit of difference if the elements had different Z coordinates.

The immediate solution in the initial MicroStation 8.9 release was to restrict pen table priority to 2D designs. Instead of rearranging the element order, the pen table would simply replace the element's display priority. This was both much more efficient than the previous implementation, and worked better to boot -- avoiding historic problems attempting to defer components of atomic units such as shared cells, dimensions, and multilines. The display priority solution worked equally well in the traditional non-rasterized print mode and the new rasterized print mode introduced in the XM Edition.

Of course, there was still demand for pen table priority in 3D designs, and mixed 2D / 3D designs. In MicroStation, the pen table application was extended to support priority for both 2D designs (using the display priority replacement technique) and pure 3D designs (using the same element order deferred draw list technique that was used in MicroStation 8.5 and earlier). The 3D deferred draw list method only worked if the configuration variable MS_LEGACYDRAWORDER was defined. Without that variable, the graphics system would work as expected for true 3D geometry -- ignoring the file order. Both of these priority implementations worked in either non-rasterized or rasterized print modes. However, pen table priority in mixed 2D / 3D designs (3D references attached to 2D master models) was still unsupported, as any attempt to reprocess a 3D element outside of its viewlet container reference would lead to unpredictable results.

To address the demand for pen table priority in mixed 2D / 3D designs, as well as 3D cells in 2D designs, a third pen table priority mode was introduced in MicroStation This new mode, called "non-rasterized priority sorting" did not modify the element's display priority nor attempt to rearrange the element file order. Instead, the elements were processed and stroked by the graphics system in their unsorted order. Once the primitive graphics were produced by the display system, they were sorted based on their pen table priority prior to being sent to the printer driver. This method had the advantage of working without regard to the dimensions of the original elements. However, since primitive graphics were not produced when printing in rasterized mode, the method was not available in all circumstances. Also, when printing a 2D design, the method was not as efficient as letting the graphics system sort the elements based on their display priority. There were some other caveats involving hardware text and OLE objects printed to a Windows printer driver, but the non-rasterized priority sorting method fit the needs of most traditional pen table priority workflows.

The sections below describe where pen table priority stands in MicroStation and later. This information may also be found in the pen table documentation. It's difficult to make a universal recommendation, as the pros and cons of each method depend on what type of data you are printing and which printer driver you are using.

If your workflow is essentially the same as it was in MicroStation 8.5, then you are probably best off modifying your pen table options to turn on the "non-rasterized priority sorting" flag. If you are using MicroStation V8 XM features such as transparency that require printing in rasterized mode, or are printing to a raster printer driver such as tiff.pltcfg, you'll need to study the other options.  In that case, the best solution may be to stop using pen table priority and instead use the native facilities in MicroStation to achieve WYSIWYG priority in the view display.

Pen Table Priority

There are three basic methods to change the natural display order of elements using a pen table:

• Prioritizing elements in a 2D design
• Prioritizing elements in a 3D design
• Non-rasterized priority sorting

Prioritizing elements in a 2D design

This section assumes that the "non-rasterized priority sort mode" pen table option is unchecked. This is the default setting.

In a pure 2D design, display priority is the preferred method for sorting elements. Display priority sorting is supported when printing in either rasterized or non-rasterized mode. When printing, designs making use of display priority do not consume any more memory than designs that do not use display priority. Display priority sorting in rasterized print mode is implemented by the graphics hardware and is more efficient that software sorting.

In a 2D design, the pen table priority output action simply replaces the effective display priority value (the sum of the reference, level, and base element priority values) of the element being modified.

Note that display priority cannot be applied to 3D elements. In practice, 3D elements often appear in 2D designs. For example, cells from 3D cell libraries that are placed in a 2D design are unaffected by pen-table-specified display priority.

A similar limitation applies to 3D references attached to 2D master models. In this situation, display priority cannot be used to prioritize elements across the 2D/3D reference boundary. For example, consider the common case of a pen table attempting to place text above all other element types. If the master model is listed last in the reference update sequence, the 2D master model elements will print on top of the text in the 3D reference despite the pen table's display priority assignments.  This can be addressed by enabling "non-rasterized priority sort mode" in the pen table.

Prioritizing elements in a 3D design

This section assumes that the "non-rasterized priority sort mode" pen table option is unchecked. This is the default setting.

Note: Unless pen table priority support in rasterized print mode is required, setting the "non-rasterized priority sort mode" pen table option is recommended when using pen table priority in conjunction with any 3D data.  In a 3D design, display priority is unsupported. Instead, the Z coordinates of the elements normally determine their display and print order.

In a 3D design, the pen table priority output action causes the element to be added to a deferred draw list. After all the non-prioritized elements have been printed, the elements within the deferred draw list are printed in increasing priority order. This technique is supported when printing in either rasterized and non-rasterized mode.

Note that some element types, such as dimensions and shared cells, are atomic in nature. Such elements may not be deferred individually. They may only be deferred as a single unit by assigning priority to the complex or compound element header.

Further note that since elements are normally eventually sorted by their Z coordinates regardless of their file order, and pen table priority in a 3D design basically just rearranges the file order, pen priority in a 3D design has no effect unless either file order display is enabled in the view's display style or all the elements have identical Z coordinates.

Important: if file order display is not enabled in the view's display style, pen table priority in a 3D design may do nothing but consume extra memory and decrease print performance.

The limitation designed for 2D display priority concerning 3D references attached to 2D master models also applies to pen table priority in 3D designs. Attempting to use pen table priority to defer an element in such a reference may yield unexpected results.

Non-rasterized priority sorting

When the pen table option "Non-rasterized priority sort mode" is set, the primitive graphics exported by the display system are sorted prior to printing. This technique only works when printing in non-rasterized mode. The non-rasterized priority sort mode does not work when printing rendered views, nor when printing to raster printer drivers such as tiff.pltcfg, cals.pltcfg, jpeg.pltcfg, or png.pltcfg.

When using the non-rasterized priority sort mode, elements not assigned a priority are printed immediately.  Elements assigned a priority are printed afterwards in order of increasing priority.

Non-rasterized priority sort mode has the advantage of working without regard to the dimensions of the source elements. Elements may be sorted across any reference boundary, and the components of complex and compound elements may be prioritized individually.

Depending on the number of elements assigned priority, the sorted graphics list may consume a significant amount of memory.

When non-rasterized priority sort mode is enabled in the pen table, some printing features are affected. These side effects include OLE objects always being rasterized when printing to the Windows printer driver, hardware/searchable text being disabled for text elements assigned priority, and elements affected by non-rectangular clip fences being clipped in software rather than by the plotter firmware. In some cases, this may result in changes to the printed output.

Troubleshooting Priority Problems

If you have elements that are not displaying or printing in the order that you want, here are a few questions that need to be answered in order to determine the cause and possible solution.

(1) What version of MicroStation are you using?

If you are not using MicroStation or later, you should obtain the latest version from Bentley Support or SELECT downloads. Earlier versions have known limitations involving reference update sequence when printing in non-rasterized mode, and do not include the 'non-rasterized priority sort mode' pen table option.

(2) What are the element types in question? Are they 2D or 3D? (It is possible to have 3D elements such as cells placed in a 2D model.)

(3) What are the elements' display priority or Z coordinate values?  Are they the same?

Often, the draw order / rasterized print order of elements with identical display priorities or Z coordinates is indeterminate.  This is due to performance reasons and the Direct 3D architecture.  When printing in non-rasterized mode, elements with identical priorities or Z coordinates are always output in file order.  This may lead to discrepencies between view display and print output. 

For example, say you have a text element overlapping a filled shape, and both have display priority of zero (or Z depth of zero).  You placed the text element in the design before the shape element.  In MicroStation 8.5 and earlier, the shape would have always displayed and printed on top.  However, in MicroStation 8.9 and later, the text may display atop the shape in the view, print atop the shape in rasterized mode, and print below the shape in non-rasterized mode.

The only reliable solution to this problem is to ensure that overlapping elements have different display priorities or Z depths.  This can be done in the design file itself, or through a pen table.

(4) Are the elements in question contained within the same model? If so, what is the dimension of that model?

(5) If the elements are in different models, what are the dimensions of those models?

(6) What is the effective model sequence? To determine that, examine the reference update sequence for each model in the hierarchy starting with the master model and determine the linear sequence in which all of the models will be displayed / printed. Here is one example:

A.dgn (2D master model, A.dgn's reference update sequence is: B, C, master model)
    +- B.dgn (3D primary reference, B.dgn's reference update sequence is: master model, b1, b2)
        +- b1.dgn (2D reference)
        +- b2.dgn (2D reference)
    +- C.dgn (3D primary reference, C.dgn's reference update sequence is: c1, c2, master model)
        +- c1.dgn (2D reference)
        +- c2.dgn (2D reference)

The effective model sequence is: B, b1, b2, c1, c2, C, A.

A characteristic of the MicroStation display system is that 2D display priorities or 3D Z coordinates sort without regard to model boundaries -- as long as the model dimensions are identical. So if your design consists of nothing but 2D models, then the elements will be arranged by their display priority values no matter what model they are contained in. The same goes for Z coordinates in a design consisting of nothing but 3D models. Complications arise in our case, with a design containing a mix of 2D and 3D models. In this situation, when a 2D/3D boundary is encountered in the model sequence, the sorting is restarted.

For my example, I've taken the effective model sequence and substituted in the dimensions of the models: 3D, 2D, 2D, 2D, 2D, 3D, 2D.

Substituting back in the model names, I've used brackets to group the models in which elements may be intermingled via display priority: B, [ b1, b2, c1, c2, ], C, A.

This indicates that elements in B will display/print below every element in all other models regardless of the display priority or Z coordinates. Elements in A will display/print above every element in all other models regardless of the display priority or Z coordinates. Elements in B, C, and A, since they are separated by dimension change boundaries, are only sorted within their own models.

If a shape element in reference b1 has a display priority of 100, and every other element in all other models has a display priority of zero, then that shape will display atop the other elements in b1, b2, c1, and c2 even though b1 occurs first in that sequence of 2D models.

The only way to resort elements across these model dimension boundaries is to print in non-rasterized mode using a pen table with its 'non-rasterized priority sort mode' option enabled.

(7) Is the MS_LEGACYDRAWORDER configuration variable defined? For MicroStation 8.11, is the 'file order' toggle turned on the appropriate display style?

(8) Is there a pen table involved? If so, what is the pen table attempting to do? Is the pen table's 'non-rasterized priority sort mode' option enabled?

(9) Are you printing in rasterized or non-rasterized mode?