"scaled image"
Shader	Background "scaled image"( "file name" LtString "" "image" LtGenericPtr NULL "softness" LtFloat 1.0 "keep texture" LtBoolean FALSE "rotation" LtEnum LI_ANGLE_DEG_0 "aspect mode" LtEnum LI_ASPECT_MODE_STRETCH "x offset" LtFloat 0.0 "y offset" LtFloat 0.0 "image brightness" LtFloat 1.0 )
Synopsis	A background of an image read from a file or supplied as an LtImage, and scaled to fit into the viewport. The image may also be rotated.
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 perserved, 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. 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 or LI_ASPECT_MODE_PRESERVE. 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. Previous page alphabetically (rpcobject) Next page alphabetically (scaletone) Index
Copyright © 1990-2004, 2005 LightWork Design Limited. All rights reserved