Name
SelectBGPic -- select a background picture as output device (V1.5)
Synopsis
SelectBGPic(id[, mode, combomode])
Function
This function selects the BGPic specified by id as the current output device. This command be used in various different modes. The usual mode to use SelectBGPic() is layers mode (#SELMODE_LAYERS) which is also the default mode. Layers mode means that all graphics data that are output by Hollywood will be added as layers to this background picture. Therefore you will have to enable layers before using this command in layers mode. Your background picture will never be modified in layers mode, it will just get more and more layers.

Alternatively, you can use the #SELMODE_NORMAL or #SELMODE_COMBO modes. These modes will modify your BGPic's data. They can only be used on BGPics that are currently not associated with a display. #SELMODE_NORMAL means that only the color channels of the BGPic will be altered when you draw to it. The transparency channel of the BGPic (can be either a mask or an alpha channel) will never be altered. You can change this behaviour by using #SELMODE_COMBO in the optional mode argument. If you use this mode, every Hollywood graphics command that is called after SelectBGPic() will draw into the color and transparency channel of the BGPic. If the BGPic does not have a transparency channel, #SELMODE_COMBO behaves the same as #SELMODE_NORMAL.

Starting with Hollywood 5.0 you can use the optional combomode argument to specify how #SELMODE_COMBO should behave. If combomode is set to 0, the color and transparency information of all pixels in the source image are copied to the destination image in any case - even if the pixels are invisible. This is the default behaviour. If combomode is set to 1, only the visible pixels are copied to the destination image. This means that if the alpha value of a pixel in the source image is 0, i.e. invisible, it will not be copied to the destination image. Hollywood 6.0 introduces the new combomode 2. If you pass 2 in combomode, Hollywood will blend color channels and alpha channel of the source image into the destination image's color and alpha channels. When you draw the destination image later, it will look as if the two images had been drawn on top of each other consecutively. Please note that the combomode argument is only supported together with #SELMODE_COMBO. It doesn't have any effect when used with the other modes.

Note that when you use #SELMODE_NORMAL or #SELMODE_COMBO, the original graphics of the BGPic are modified. You will always be drawing to the original graphics of the BGPic. Imagine that you have a 640x480 BGPic that is currently scaled to 800x600 because you called ChangeDisplaySize(). If you call SelectBGPic() with #SELMODE_NORMAL or #SELMODE_COMBO now on this BGPic, you will actually be drawing to the 640x480 picture. The 800x600 picture will be updated when EndSelect() is called. On EndSelect(), Hollywood will scale the original graphics to the current output size of the BGPic, but your initial drawing will always occur on the original BGPic.

An alternative way to draw into the transparency channels of a BGPic is to do this separately using SelectMask() or SelectAlphaChannel(). These two commands, however, will write data to the transparency channel only. They will not touch the color channel. So if you want both channels, color and transparency, to be affected, you need to use SelectBGPic() with mode set to #SELMODE_COMBO.

When you are finished with rendering to your BGPic and want your display to become the output device again, just call EndSelect().

Only commands that output graphics directly can be used after SelectBGPic(). You may not call animated functions like MoveBrush() or DisplayBrushFX() while SelectBGPic() is active.

When mode is set to #SELMODE_LAYERS, SelectBGPic() can also come handy when you want to make multiple changes to the layers of the current BGPic without causing a refresh after each change. For example, you may want to insert 100 new layers at once. This would be pretty slow if you would do it in the conventional way because Hollywood would refresh the display a hundred times. To avoid this, you can simply call SelectBGPic() and insert the 100 layers and Hollywood will not refresh the display before you call EndSelect(). Inside a SelectBGPic()-EndSelect() block, you can do as many changes as you like. They will not be drawn before EndSelect() is called. See below for an example.

Inputs
id
background picture which shall be used as output device
mode
optional: rendering mode to use (see above); this can be either #SELMODE_LAYERS, #SELMODE_NORMAL or #SELMODE_COMBO; defaults to #SELMODE_LAYERS (V4.5)
combomode
optional: mode to use when #SELMODE_COMBO is active (see above); defaults to 0 (V5.0)
Example
EnableLayers()
SelectBGPic(2)
TextOut(#CENTER, #CENTER, "Hello World")
Box(0, 0, 100, 100, #RED)
Box(#RIGHT, #BOTTOM, 100, 100, #BLUE)
EndSelect()
DisplayBGPic(2)
The above code selects background picture 2 as the current output device and adds three layers to it (one text and two rectangles). After that, the display is selected as the output device and then background picture 2 is displayed with its three layers.


SetFillStyle(#FILLCOLOR)
EnableLayers
SelectBGPic(1)    ; we assume that 1 is our current BGPic
; add 100 random layers
For Local k = 1 To 100
   Box(Rnd(540), Rnd(380), 100, 100, RGB(Rnd(255), Rnd(255), Rnd(255)))
Next
EndSelect       ; now the 100 layers are drawn in one go!
This code illustrates the case discussed above. You need to make lots of changes and you want to defer drawing for performance reasons. In our case, we want to add 100 layers to the current BGPic. So we encapsulate this code by a SelectBGPic()-EndSelect block. Hollywood will silently add the 100 layers and will draw them in one go when EndSelect() is called. This is much faster than adding them without SelectBGPic() because in that case every call to Box() would cause a refresh.

Show TOC