27.17 Standard draw tags

Starting with Hollywood 4.0, most of the drawing functions accept an optional table argument now, which lets you configure further options. For example, you can specify tags which will automatically scale or rotate the graphics before displaying it.

Many of the standard drawing tags only work when layers are enabled. Some, however, can also be used when layers are off. Note that the graphics data of the source object will never be changed. If layers are on Hollywood will insert the new layer and immediately apply any transformation before the layer is made visible. If layers are off a copy of the original graphics will be made. The original graphics data will never be changed (in contrast to functions like ScaleBrush(), RotateBrush(), TransformBrush() etc. which modify the brushes data). Thus, you can be sure that you will always get the best quality when using the standard draw tags to apply transformations, because Hollywood will always use the original graphics data.

For every standard draw tag there is a default value that is used when the tag is not specified. You can modify this default setting using the new SetDrawTagsDefault() command which allows you to define new default values for each tag. This is very useful if you would like to permanently use a different default value for a certain tag; for example, if you permanently want to use an anchor point of 0.5/0.5 instead of 0.0/0.0, or if you want to change the default layer insert position from frontmost to backmost etc.

The following standard tags are currently defined:

Width, Height:

If you specify these tags, the object will be scaled to the specified dimension and then displayed. (V4.0)

Rotate:

This tag will rotate the graphics by the specified degrees and then display it. (V4.0)

SmoothScale:

If this is set to True, scaling and/or rotation will be done using anti-aliased interpolation. This looks better but is a lot slower. (V4.0)

ScaleX, ScaleY:

This is an alternative way of scaling the object. You have to pass a floating point value here that indicates a scaling factor. For example, 0.5 means half the size, 2.0 means twice the size. This is especially convenient if you would like to keep the proportions of the object that you want to scale. If you use the same factor for ScaleX and ScaleY, the proportions of the graphics will remain intact. Please note that ScaleX/Y and Width/Height are mutually exclusive. You must not mix both groups. Either use ScaleX/Y, or stick to Width/Height. (V4.5)

Transform:

This tag allows you to specify a 2x2 transformation matrix. Transformation matrices are useful if you want to apply scaling and rotation at the same time, or if you want to mirror an object. You have to pass a table to Transform. The table must contain the four constituents of a 2x2 transformation matrix in the following order: sx, rx, ry, sy. See TransformBrush for more information about transformation matrices. Please note that the Transform tag is mutually exclusive with the following tags: Width/Height/ScaleX/ScaleY/Rotate. You must not combine it with any of these tags. (V4.5)

AnchorX, AnchorY:

You can use these two tags to specify the anchor point of the graphics object (sometimes the anchor point is referred to as the 'hot spot'). The anchor point can be any point between 0.0/0.0 (top left corner of the graphics object) and 1.0/1.0 (bottom right corner of the graphics object). The center of the graphics object would be defined by anchor point of 0.5/0.5. All transformations (scaling, rotation etc.) will be applied relative to the anchor point. Also, the position of an object is always relative to the anchor point. For example, take a look at the following code:

DisplayBrush(1, 0, 0, {AnchorX = 0.5, AnchorY = 0.5})

This call will make the brush's center appear at 0:0 because the anchor point is set to 0.5/0.5. If you want the brush's top left corner to appear at 0:0, you will have to use an anchor point of 0.0/0.0 (which is also the default anchor point, so you do not have to specify it at all). Anchor points are most of the time only used when layers are enabled. However, you can also use AnchorX/Y if layers are off. See SetLayerAnchor for some more information about the anchor point concept. (V4.5)

Hidden:

Allows you to create a layer that is initially hidden. If you set this tag to True, the graphics will be inserted as a layer but nothing will be shown because the layer is kept hidden. This function is only available with enabled layers. Defaults to False. (V4.5)

InsertPos:

Allows you to specify the insert position for the new layer. The layer will be inserted at this position with all other layers being shifted down in the hierarchy. The first layer is at position 1. Specifying a position of 0 here will insert the layer as the last layer. This is also the default setting. You can also specify the name of a layer at whose position the new layer should be inserted. This is perfectly allowed. Of course, this function only works with enabled layers. (V4.5)

Name:

This tag can be used to assign a name to the layer right at creation time. This is pretty much the same as calling the SetLayerName() function on the layer right after inserting it. Specifying the Name tag here just saves you some typing and makes the code more readable. This tag is only handled when layers are enabled. By default, no names are given to new layers. By default, they can only be referred to using IDs. (V4.5)

Group:

If layers are enabled, you can use this tag to attach the layer to a group right at creation time. This is pretty much the same as calling the GroupLayer() function on the layer right after creating it. Specifying the Group tag here just saves you some typing and makes the code more readable. This tag is only handled when layers are enabled. See GroupLayer for details. (V10.0)

Transparency:

You can use this tag to specify a global transparency setting for this graphics object. This can be a value ranging from 0 (no transparency) to 255 (full transparency), or alternatively, a string containing a percentage (e.g. "50%" for half shine through transparency). Defaults to 0 which means no global transparency. (V4.5)

GlobalTransparency:

This is only supported when layers are enabled. If it is set to True, the layer's transparency setting set using the Transparency tag or using functions like SetLayerTransparency() will also be applied to the layer's shadow. For some reason Hollywood never did that by default and in order to maintain compatibility with scripts which expect the old behaviour the functionality has been added using a new tag. If you want to globally enable the new behaviour for all your layers, just call SetDrawTagsDefault() with GlobalTransparency set to True. (V9.1)

Tint:

You can use this tag to specify a global color tinting setting for this graphics object. This can be a value ranging from 0 (no tinting) to 255 (full color tinting), or alternatively, a string containing a percentage (e.g. "50%" for medium color tinting). If you set this tag to anything else than 0, you must also provide a tint color in the TintColor tag (see below). Defaults to 0 which means no tinting. Starting with Hollywood 5.0 this tag is directly mapped to the Tint filter. Thus, specifying the Tint tag is the same as specifying a Tint filter in the Filters table below. (V4.5)

TintColor:

Only required if you also specify Tint. In that case, you have to specify a RGB color color here that will be used for tinting. (V4.5)

Shadow:

If you set this tag to True, the graphics object will be drawn with a drop shadow. You can configure the look of the shadow using the ShadowDir, ShadowSize, ShadowColor, and ShadowRadius tags. See below for more information. This tag is only supported when layers are turned on. See SetLayerShadow for details. (V5.0)

ShadowDir:

Specifies the direction of the shadow. This must be set to one of Hollywood's directional constants. This tag is only handled when Shadow is set to True (see above). (V5.0)

ShadowColor:

Specifies the color of the shadow. This must be an ARGB value that can contain a transparency setting. This tag is only handled when Shadow is set to True (see above). (V5.0)

ShadowPen:

When palette mode is set to #PALETTEMODE_PEN and the drawing target uses a palette, the shadow will be drawn using the pen specified here instead of the color specified in the ShadowColor tag from above. (V9.0)

ShadowSize:

Specifies the size of the shadow. This tag is only handled when Shadow is set to True (see above). (V5.0)

ShadowRadius:

Specifies the shadow radius. This tag is only handled when Shadow is set to True (see above). (V5.0)

Border:

This tag can be used to draw the graphics object with a border frame. You can configure the look of the border using the BorderSize and BorderColor tags. Please see below for more information. This tag is only supported when layers are turned on. See SetLayerBorder for details. (V5.0)

BorderColor:

Specifies the color of the border. This must be an ARGB value that can contain a transparency setting. This tag is only handled when Border is set to True (see above). (V5.0)

BorderPen:

When palette mode is set to #PALETTEMODE_PEN and the drawing target uses a palette, the border will be drawn using the pen specified here instead of the color specified in the BorderColor tag from above. (V9.0)

BorderSize:

Specifies the size of the border. This tag is only handled when Border is set to True (see above). (V5.0)

Filters:

This tag can be used to apply filters to this graphics object. You have to pass a table to this tag that describes the desired configuration of the single filters. See SetLayerFilter for more information on how this table needs to be organized. Note that although the documentation points to the layers library, the Filters tag actually also works when layers are disabled. (V5.0)