25.18 Scaling engines

Starting with Hollywood 4.0, there are two scaling engines available which you can use to force your script to run in a different resolution than it was designed for. For example, you wrote a little game in 320x240 so that it runs fast enough on classic Amigas. On modern Amigas, however, 320x240 will appear as a tiny window. Thus, you can now use Hollywood's scaling engines to make your script appear in 640x480 or 800x600 without changing a single line of your code! All you have to do is activate one of Hollywood's scaling engines!

When a scaling engine is active, your script will still think that it is running in its original resolution. This means, for instance, that calls like

width = GetAttribute(#DISPLAY, 0, #ATTRWIDTH)
height = GetAttribute(#DISPLAY, 0, #ATTRHEIGHT)

will still return 320x240 even though your script is now running in a completely different resolution. It is obvious that such a behaviour is necessary for consistency i.e. to ensure that the script runs flawlessly in the new resolution. Your script will not notice that a scaling engine is active at all! The scaling engine will be installed completely transparently on top of your script.

Scaling engines can be activated either from the command line by using one of the scaling engine arguments (-autoscale or -layerscale) or it can be activated from within your script by either specifying ScaleMode in a @DISPLAY preprocessor command or by calling SetDisplayAttributes().

Hollywood offers two scaling engines:

  1. Auto scaling engine: You can activate this scaling engine by specifying the -autoscale argument or using #SCALEMODE_AUTO with @DISPLAY or SetDisplayAttributes(). This scaling engine is a lowlevel scaling engine which will simply scale all of Hollywood's graphical output to the new dimensions. Because of this very nature, the auto scaling engine will work with all Hollywood scripts without exceptions. The drawback of the auto scaling engine is a) that it can get quite expensive on the CPU in case the host system doesn't support hardware-accelerated scaling b) that it scales vector graphics in bitmap mode which means that, for instance, true type fonts, graphics primitives, or vector brushes will deteriorate in quality, and c) that drawing is slower because the whole display has to be refreshed even if only a single pixel has changed. You can improve the performance of the auto scaling engine by using a double buffer for drawing for encapsulating all your drawing commands inside a BeginRefresh() and EndRefresh() section. See BeginRefresh for details. Another option to greatly improve the performance of the auto scaling engine is to use a plugin which supports hardware-accelerated scaling, e.g. the GL Galore or RebelSDL plugins. Plugins which support hardware-accelerated scaling can apply auto scaling in almost no time. So if Hollywood's inbuilt auto scaling performance is too poor for your requirements, you might want to use a plugin which supports hardware-accelerated scaling. See Obtaining plugins for details.

  2. Layer scaling engine: The layer scaling engine is a more sophisticated, high-level scaling engine which you can activate by specifying the -layerscale argument or using #SCALEMODE_LAYER with @DISPLAY or SetDisplayAttributes(). This scaling engine a) is often faster than the auto scaling engine because layers have only to be scaled once, b) offers a higher output quality for vector graphics (i.e. graphics primitives, vector brushes, true type text) which can be scaled without loss of quality, and c) draws faster because only parts of the display need to be refreshed. The drawback of the layer scaling engine is that it works only when Hollywood is in layer mode and it needs more memory. Also, you cannot call DisableLayers() when the layer scaling engine is active. Thus, if you want to use the layer scaling engine, your whole script has to run with enabled layers.

From these descriptions it might sound like option (2) is the way to go, but this is not necessarily true. In fact, the auto scaling engine is pretty sufficient in most cases. The layer scaling engine is only important for projects like presentations that shall be promoted to a UltraHD resolution or similar. In that case, it is important that the vector graphics are property scaled in vector mode so that a crisp result is achieved. Under normal circumstances, however, using the auto scaling engine should do everything you want. And don't be discouraged by the fact that it is slower than the layer scaling engine - on modern systems you probably won't notice this slowdown at all!

When activating a scaling engine, you also have to specify the target scaling resolution. This can be done in two different ways: You can either set the target scaling resolution using the -scalewidth and -scaleheight console arguments or their counterparts ScaleWidth and ScaleHeight if you are using @DISPLAY or SetDisplayAttributes(), or you can set a global scaling coefficient using the -scalefactor or -systemscale console arguments or their runtime counterparts accepted by @DISPLAY or SetDisplayAttributes().

Note that there is a difference in behaviour between setting the target resolution using ScaleWidth and ScaleHeight, and between setting the scaling resolution using ScaleFactor and SystemScale. If you use ScaleWidth and ScaleHeight, the size passed to these tags will be rigidly enforced and your display will always keep this size, even if the script requests to change it by calling ChangeDisplaySize() or by showing a background picture that is of a different size using DisplayBGPic(). The only way the display size can be changed when ScaleWidth and ScaleHeight were used to set the scaling resolution is that the user resizes the window. Otherwise the display will never change its dimensions.

When using ScaleFactor or SystemScale, on the other hand, a scaling coefficient is applied to the current display size. This means that the target scaling size is not static as it is the case with ScaleWidth and ScaleHeight (see above), but it is dynamic because it is relative to the current display size, e.g. if a scaling coefficient of 2.0 is applied and a display is first 640x480 pixels in size and later 800x600 pixels in size, the display will first be promoted to 1280x960 pixels and then to 1600x1200 pixels. This is what makes ScaleFactor perfect for scaling a script for a high dpi display because it makes sure that the script behaves exactly the same but just appears larger (or smaller if you want!).

There is also the difference that, in case a scaling engine is active, SizeWindow events are only delivered to your display if you use either ScaleFactor or SystemScale to set the target scaling resolution. If you use ScaleWidth and ScaleHeight, no SizeWindow events will be sent to your display because window size changes are handled by the scaling engine.

If you activate a scaling engine but specify neither -scalewidth, -scaleheight, nor -scalefactor or -systemscale the scaling engines won't be activated until the user resizes the window. As soon as he does this, the new window size will be set as the target scaling size.

Finally, you can specify the -smoothscale argument to enable interpolated anti-alias scaling for bitmap graphics which looks better but can be slower if no hardware-accelerated scaling is available.

Show TOC