"scaled image"
Class	Background
Synopsis	A background of an image read from a file or supplied as an image in memory, and scaled to fit into the viewport. The image may also be rotated.
Arguments	"file name" Type: LtString Default: "" Range: - Hint: - "image" Type: LtGenericPtr Default: NULL Range: - Hint: - "softness" Type: LtFloat Default: 1.0 Range: [ 0, inf ] Hint: - "keep texture" Type: LtBoolean Default: FALSE Range: - Hint: - "rotation" Type: LtEnum Default: LI_ANGLE_DEG_0 Range: 0, 270, 90, 180 Hint: - "aspect mode" Type: LtEnum Default: LI_ASPECT_MODE_STRETCH Range: 0, 1, 2, 3, 4 Hint: - "x offset" Type: LtFloat Default: 0.0 Range: [ -1, 1 ] Hint: - "y offset" Type: LtFloat Default: 0.0 Range: [ -1, 1 ] Hint: - "image brightness" Type: LtFloat Default: 1.0 Range: [ 0, inf ] Hint: - "border colour" Type: LtColour Default: (1.0, 1.0, 1.0) Range: [ 0, inf ], [ 0, inf ], [ 0, inf ] Hint: [ 0, 1 ], [ 0, 1 ], [ 0, 1 ]
Location	lishlite
Description	The name of the file containing the image data may be provided as a string to parameter "file name", which can be in any format for which the appropriate image driver is installed. Alternatively a pointer to a valid LtImage data structure may be given via parameter "image". If the value NULL is given then the image will be extracted from the file represented by "file name", otherwise the "image" parameter takes precedence. It is the application's responsibility to ensure that the image pointed to by "image" remains valid throughout the lifetime of the shader. This can be done in two ways; either by simply ensuring that the original LtImage structure remains untouched, or by using the "keep texture" parameter. This is done by `switching' the shader to keep the texture after it has been created. The shader is initially created with the "image" argument pointing to a valid LtImage and the "keep texture" argument set to FALSE. The shader is then reset using LiShaderReset. The shader's arguments are then altered so that "image" is NULL and "keep texture" is TRUE. The LtImage can then safely be destroyed. If the "keep texture" argument is TRUE then the arguments "image" and "file name" are taken into account only if no texture has been created yet. Switching the parameter to FALSE will result in rebuilding the texture during the next call to LiShaderReset or to a shaded rendering execution method. The way in which the image is scaled to fit the viewport is set using the "aspect mode" parameter. The value can be any one of the following: Value Meaning LI_ASPECT_MODE_STRETCH The image is automatically scaled to fit the viewport. This is the default setting. LI_ASPECT_MODE_PRESERVE The pixel aspect ratio of the image is preserved (which may result in part of the image being cropped). This is equivalent to setting the obsolete "keep aspect" parameter to TRUE. LI_ASPECT_MODE_LETTERBOX The pixel aspect ratio of the image is preserved, with the image centred in the viewport. The entire image is always visible. A black border may appear above and below, or to the sides of the image. LI_ASPECT_MODE_VIEW The pixel aspect ratio of the image is preserved, with scaling and positioning to be consistent with changes in viewport size. The image may be cropped, or have borders, depending on the view and image aspect ratios. LI_ASPECT_MODE_CENTRE Locks the background image to the centre of the view, keeping the aspect ratio the same as the source image. This ensures that the entire background is covered. One side of the source image is fitted to completely fill the view and then the other side of the source image is clipped to maintain the aspect ratio. LI_ASPECT_MODE_REPEAT This mode does not scale the image but repeats it to fill the view. It makes "scaled image" behave the same as the "image" background shader, but with the added advantage of being able to set offsets, rotations, image brightness and softness. The "x offset" and "y offset" parameters allow the image to be moved relative to the viewport. Sensible values are between -1.0 and 1.0, although other values may be set if desired. At the moment the offsets are only applied if "aspect mode" is LI_ASPECT_MODE_STRETCH, LI_ASPECT_MODE_PRESERVE or LI_ASPECT_MODE_REPEAT. LI_ASPECT_MODE_LETTERBOX and LI_ASPECT_MODE_VIEW calculate their own offsets and ignore these parameters. The image may also be rotated through either 90, -90, or 180 degrees via the parameter "rotation". Note that supplying any other number for this parameter will have no effect. Predefined values of the parameters are given by LI_ANGLE_DEG_0, LI_ANGLE_DEG_90, LI_ANGLE_DEG_MINUS_90 and LI_ANGLE_DEG_180. These should always be used rather than passing numbers directly. The brightness of the image may be manipulated using the "image brightness" parameter. This is applied to the background colour as a simple scale factor. The parameter "softness" controls the degree of blurring on the image texture. The "border colour" parameter determines what colour will be used when a sample does not fall within the bounds of the image (e.g., the 'edge' colour in letterbox mode). Previous page alphabetically (rpcobject) Next page alphabetically (scaletone) Index
Copyright © 1990-2005, 2006 LightWork Design Limited. All rights reserved