Frogans Technology OP3FT FSDL 3.0 September 29, 2015 Preliminary Draft #1 ISBN n/a Frogans Slide Description Language (FSDL) - 3.0 EXTRACT and elements Status This document is a preliminary draft, for examination, review, and evaluation by the developer community. Aspects of this document may be discussed publicly on the Frogans technology mailing lists, accessible at the following permanent URL: https://lists.frogans.org/. Location This document is accessible at the following permanent URL: https://www.frogans.org/en/resources/fsdl/access.html Copyright Statement This document must be used in compliance with the Frogans Technology User Policy, accessible at the following permanent URL: https://www.frogans.org/en/resources/ftup/access.html. Copyright (C) 2015 OP3FT. All rights reserved. OP3FT Frogans Technology [Page 1] FSDL 3.0 Preliminary Draft #1 September 2015 6.3. Preparing Image Resources - Element The element prepares an image resource that is based on an image file. The image file contains a pre-authored image, which is created previously using image editing software. The element is a child of the element (see Section 6.1). The element does not contain any children. It does not contain text characters. As stated in the Frogans slide layout rules (Section 4.6): - The image resource is intended to be used in the Frogans slide as the foundation of a layer (see the element in Section 6.12) or as part of a merged resource (see the and elements in Section 6.11). - The image resource can be used once or several times in the Frogans slide. - The image file on which the image resource is based is defined using a element (see Section 6.2). The image resource is identified using a component identifier (Section 4.5). The image file is referred to using a component identifier. The image file is either a static or a dynamic auxiliary file in the Frogans site root directory (Section 4.1), or is embedded as text characters in the element, depending on the value of the "nature" attribute of the element. The image file is encoded using one of the following image formats: PNG [PNG], JPEG [JPEG], or GIF [GIF]. If the image file contains information on the degree of opacity of its pixels, such as an alpha channel that can be defined using the PNG image format, then this information is used when preparing the image resource. Otherwise, the pixels in the image file are considered fully opaque when preparing the image resource. In application of the FSDL design principle on avoiding on-screen distractions (Section 1.4), if the image file is encoded using the GIF image format and contains an animation, then only the first frame is used when preparing the image resource. For more information on the process to decode image files, see OP3FT Frogans Technology [Page 27] FSDL 3.0 Preliminary Draft #1 September 2015 Appendix A.1. If the image file is an auxiliary file, then according to Appendix A.1 on decoding image files, the image file extension is not required in the "name" attribute of the element. In application of the FSDL design principle on saving device resources (Section 1.4), the width and height of the pre-authored image are both limited to 1,024 pixels. A selection of the pre-authored image is used, representing either the entire pre-authored image, or an extract of the pre-authored image. Using an extract of the pre-authored image can be helpful if, in order to reduce latency for loading the Frogans slide, the pre- authored image is an image sprite, i.e. it contains a collection of images. The image selection depends on the values of the "selection" and "bounds" attributes of the element. By default, the image selection is the entire pre-authored image. The way in which the image selection is incorporated in the image resource depends on the values of the "aspect", "adjust", and "origin" attributes of the element. The size, in pixels, of the image selection is not necessarily the same as the size, in pixels, of the image resource. If the image file is an auxiliary file, then its size, in bytes, is subject to the overall file size limitations applicable to the Frogans slide (Section 4.4). If the image file is embedded as text characters in the element, then the text characters represent the contents of the image file encoded using Base64 (see Section 6.2). Embedding an image file as text characters in the element reduces latency for loading the Frogans slide, since both the FSDL document and the image file are loaded at the same time. Embedding an image file can also simplify the task for generating both the FSDL document and the image file on the fly (i.e. dynamically) on the server hosting the Frogans site. However, embedding an image file as text characters in the element leads to an overhead to be taken into account in the overall file size limitations applicable to the Frogans slide (Section 4.4), since the number of text characters required to encode the image file is approximately 1.33 times the size in bytes of the image file. Furthermore, depending on the character encoding of the FSDL document OP3FT Frogans Technology [Page 28] FSDL 3.0 Preliminary Draft #1 September 2015 (Section 5.3), more than one byte may be necessary to encode each text character. Finally, an embedded image file cannot benefit from potential inclusion in the auxiliary file cache (Section 4.3). During the rendering of the Frogans slide, when preparing the image resource, a placeholder image is used instead of the image selection in the following cases: * if the image file is an auxiliary file in the Frogans site root directory and it cannot be retrieved for any reason (such as a network failure, or if the image file does not exist) * if the image file cannot be decoded, whether or not the image file is embedded as text characters in the element * if the width or height of the pre-authored image, in pixels, exceeds the limits indicated above If a placeholder image is used, then it has the same size, in pixels, as the image resource. In this case, the values of the "selection", "bounds", "aspect", "adjust", and "origin" attributes of the element are ignored. For more information on the process to generate placeholder images, see Appendix A.2. The element has the following attributes: resid - Mandatory The identifier of the image resource. The value of the attribute is a component identifier. The value is compliant with the rules presented in Section 4.5. As a result, the value cannot have been utilized previously in the FSDL document as a component identifier. Examples of accepted values: resid='foo1' resid='Foo1' resid='foo2' resid='foo_1' Examples of refused values: resid='' OP3FT Frogans Technology [Page 29] FSDL 3.0 Preliminary Draft #1 September 2015 resid='foo-1' resid='foo/1' resid='foo.1' resid='foo 1' resid='foo1, foo2' size - Mandatory The size of the image resource. The value of the attribute represents the width and height, in pixels, of the image resource. As stated in the Frogans slide layout rules (Section 4.6), the width of the image resource is an integer between 1 and 640 (inclusive) and its height is an integer between 1 and 480 (inclusive). The value of the attribute is a string in the 'width,height' pattern where: ',' is the U+002C COMMA character; 'width' and 'height' are each a substring representing respectively the width or height of the image resource. Each substring contains between one and three decimal characters (inclusive). Each decimal character of the substring is in the range from '0' to '9' (U+0033 DIGIT ZERO to U+0039 DIGIT NINE, inclusive). The substring does not contain any leading '0' (U+0033 DIGIT ZERO) characters. As a result, the value of the attribute does not contain any of the following characters: space (U+0020 SPACE), '+' (U+002B PLUS SIGN), '-' (U+002D HYPHEN-MINUS), and '.' (U+002E FULL STOP). Examples of accepted values: size='40,200' size='400,200' Examples of refused values: size='' size='400,0' size='400,550' size='400' size='400 200' size='040,200' size='400, 200' size='+400,200' size='400,-200' size='400.5,200' fileref - Mandatory OP3FT Frogans Technology [Page 30] FSDL 3.0 Preliminary Draft #1 September 2015 The identifier referencing the image file on which the image resource is based. The value of the attribute is a component identifier. The value is compliant with the rules presented in Section 4.5. The value of the attribute has been utilized previously in the FSDL document as a component identifier for a element. Examples of accepted values: fileref='foo1' fileref='Foo1' fileref='foo2' fileref='foo_1' Examples of refused values: fileref='' fileref='foo-1' fileref='foo/1' fileref='foo.1' fileref='foo 1' fileref='foo1, foo2' selection - Optional The image selection used in the image resource. The attribute is based on a string set which represents the possible values of the attribute. The value of the attribute is case-sensitive. The value can be: * 'entire' indicates that the image selection is the entire pre- authored image. * 'extract' indicates that the image selection is an extract of the pre-authored image. The extract depends on the value of the "bounds" attribute of the element. The default value is 'entire'. bounds - Applicable only if the value of the "selection" attribute equals 'extract'. Mandatory if applicable. OP3FT Frogans Technology [Page 31] FSDL 3.0 Preliminary Draft #1 September 2015 The bounds of the image selection used in the image resource. The value of the attribute represents the left, top, right, and bottom coordinates, in pixels, of the image selection in the pre- authored image. The left and top coordinates are integers between 0 and 1,023 (inclusive). The right and bottom coordinates are integers between 1 and 1,024 (inclusive). The image selection uses an x,y coordinate system where: the x and the y coordinates of the pixel at the top-left corner of the pre- authored image are both zero; values on the x axis increase towards the right; values on the y axis increase towards the bottom. The image selection is made as follows: * The left coordinate is equal to the x coordinate of the pixel at the top-left corner of the image selection. * The top coordinate is equal to the y coordinate of the pixel at the top-left corner of the image selection. * The right coordinate is equal to one plus the x coordinate of the pixel at the bottom-right corner of the image selection. The right coordinate is greater than the left coordinate. * The bottom coordinate is equal to one plus the y coordinate of the pixel at the bottom-right corner of the image selection. The bottom coordinate is greater than the top coordinate. As a result, the width of the image selection is equal to the right coordinate minus the left coordinate, and the height of the image selection is equal to the bottom coordinate minus the top coordinate. The value of the attribute is a string in the 'left,top,right,bottom' pattern where: ',' is the U+002C COMMA character; 'left', 'top', 'right', and 'bottom' are each a substring representing respectively the left, top, right, or bottom coordinate. Each substring contains between one and four decimal characters (inclusive). Each decimal character of each substring is in the range from '0' to '9' (U+0030 DIGIT ZERO to U+0039 DIGIT NINE, inclusive). The substrings do not contain any leading '0' (U+0033 DIGIT ZERO) characters. OP3FT Frogans Technology [Page 32] FSDL 3.0 Preliminary Draft #1 September 2015 As a result, the value of the attribute does not contain any of the following characters: space (U+0020 SPACE), '+' (U+002B PLUS SIGN), '-' (U+002D HYPHEN-MINUS), and '.' (U+002E FULL STOP). Examples of accepted values: bounds='50,30,150,130' bounds='250,30,450,130' Examples of refused values: bounds='' bounds='50,30,1500,130' bounds='150,30,50,130' bounds='50,30' bounds='50 30 150 130' bounds='050,30,150,130' bounds='50, 30,150,130' bounds='+50,30,150,130' bounds='50,-30,150,130' bounds='50.5,30,150,130' During the rendering of the Frogans slide, when preparing the image resource: * If the left coordinate is greater than the width of the pre- authored image minus one, then the image selection is empty. In this case, the prepared image resource is fully transparent. * If the top coordinate is greater than the height of the pre- authored image minus one, then the image selection is empty. In this case, the prepared image resource is fully transparent. * If the right coordinate is greater than the width of the pre- authored image, then the right coordinate is considered to be equal to the width of the pre-authored image. * If the bottom coordinate is greater than the height of the pre- authored image, then the bottom coordinate is considered to be equal to the height of the pre-authored image. aspect - Optional The aspect of the image selection in the image resource. The attribute is based on a string set which represents the possible values of the attribute. The value of the attribute is case-sensitive. OP3FT Frogans Technology [Page 33] FSDL 3.0 Preliminary Draft #1 September 2015 The value can be: * 'base' indicates that the image selection is resized, maintaining its original proportions, such that the whole image selection occupies either the entire width or the entire height of the image resource. Any remaining parts of the image resource that are not occupied by the image selection are fully transparent. The placement of the image selection in the image resource depends on the value of the "adjust" attribute of the element. * 'spread' indicates that the image selection is resized, without maintaining its original proportions, such that the image selection occupies the entire width and height of the image resource. * 'zoom' indicates that the image selection is resized, maintaining its original proportions, such that the image selection occupies the entire width and height of the image resource. The image selection is cropped in order to fit in the image resource if its proportions are different from the proportions of the image resource. The placement of the image selection in the image resource depends on the value of the "adjust" attribute of the element. * 'echo' indicates that the image selection is resized, maintaining its original proportions, such that the whole image selection occupies either the entire width or the entire height of the image resource. Any remaining parts of the image resource that are not occupied by the image selection are covered by copies of the image selection that are placed next to one another, either vertically or horizontally. Copies of the image selection are cropped in order to fit in the image resource if their placement makes them extend beyond the edge of the image resource. The placement of the image selection in the image resource depends on the value of the "adjust" attribute of the element. * 'tile' indicates that the image selection is not resized. Any remaining parts of the image resource that are not occupied by the image selection are covered by copies of the image selection that are placed next to one another, both vertically and horizontally. The image selection and copies of the image selection are cropped in order to fit in the image resource if their placement makes them extend beyond the edge of the image resource. The placement of the image selection in the image resource depends on the value of the "origin" attribute of the element. OP3FT Frogans Technology [Page 34] FSDL 3.0 Preliminary Draft #1 September 2015 The default value is 'base'. For more information on the process to resize image selections, see Appendix A.3. adjust - Applicable only if the value of the "aspect" attribute of the element equals 'base', 'zoom', or 'echo'. Optional if applicable. The adjustment of the image selection in the image resource. The value of the attribute represents an integer between -100 and 100 (inclusive). The adjustment is applied, either horizontally or vertically, as follows: * An adjustment of -100 corresponds to the LT placement, where the image selection is placed so that its left or top edge matches the left or top edge of the image resource. * An adjustment of 0 corresponds to the central placement, where the image selection is centered vertically or horizontally in the image resource. * An adjustment of 100 corresponds to the RB placement, where the image selection is placed so that its right or bottom edge matches the right or bottom edge of the image resource. * An adjustment between -100 and 0 (exclusive) corresponds to a proportional placement, where the image selection is placed according to the absolute value of the adjustment, starting from the central placement and moving towards the LT placement. For instance, an adjustment of -25 corresponds to a placement where the image selection is placed one-quarter of the way from the central placement towards the LT placement. * An adjustment between 0 and 100 (exclusive) corresponds to a proportional placement, where the image selection is placed according to the value of the adjustment, starting from the central placement and moving towards the RB placement. For instance, an adjustment of 75 corresponds to a placement where the image selection is placed three-quarters of the way from the central placement towards the RB placement. The default value is 0. OP3FT Frogans Technology [Page 35] FSDL 3.0 Preliminary Draft #1 September 2015 The value of the attribute is a string containing between one and three decimal characters (inclusive), preceded by a leading sign if the adjustment is less than zero. The leading sign is the '-' (U+002D HYPHEN-MINUS) character. Each decimal character of the string is in the range from '0' to '9' (U+0030 DIGIT ZERO to U+0039 DIGIT NINE, inclusive). The string does not contain any leading '0' (U+0033 DIGIT ZERO) characters. As a result, the value of the attribute does not contain any of the following characters: space (U+0020 SPACE), '+' (U+002B PLUS SIGN), and '.' (U+002E FULL STOP). Examples of accepted values: adjust='0' adjust='-100' adjust='100' adjust='-25' adjust='75' Examples of refused values: adjust='' adjust='-120' adjust='150' adjust='-025' adjust='075' adjust='- 25' adjust='+100' adjust='-25.5' origin - Applicable only if the value of the "aspect" attribute of the element equals 'tile'. Optional if applicable. The origin in the image selection used in the image resource. The value of the attribute represents the x and y coordinates, in pixels, of the origin in the image selection. The x and y coordinates correspond to the horizontal and vertical coordinates, respectively, of the pixel in the image selection that is placed in the top-left corner of the image resource. The x and y coordinates are integers between 0 and 1,023 (inclusive). The x and y coordinates of the top-left corner of the image selection are both zero. OP3FT Frogans Technology [Page 36] FSDL 3.0 Preliminary Draft #1 September 2015 The default value is '0,0'. The value of the attribute is a string in the 'x,y' pattern where: ',' is the U+002C COMMA character; 'x' and 'y' are each a substring representing respectively the x or y coordinate. Each substring contains between one and four decimal characters (inclusive). Each decimal character of each substring is in the range from '0' to '9' (U+0033 DIGIT ZERO to U+0039 DIGIT NINE, inclusive). The substrings do not contain any leading '0' (U+0033 DIGIT ZERO) characters. As a result, the value of the attribute does not contain any of the following characters: space (U+0020 SPACE), '+' (U+002B PLUS SIGN), '-' (U+002D HYPHEN-MINUS), and '.' (U+002E FULL STOP). Examples of accepted values: origin='0,0' origin='50,30' origin='250,30' Examples of refused values: origin='' origin='50,3000' origin='50' origin='50 30' origin='050,30' origin='50, 30' origin='+50,30' origin='50,-30' origin='50.5,30' During the rendering of the Frogans slide, when preparing the image resource: * If the x coordinate is greater than the width of the pre- authored image minus one, then the x coordinate is considered to be equal to the width of the pre-authored image minus one. * If the y coordinate is greater than the height of the pre- authored image minus one, then the y coordinate is considered to be equal to the height of the pre-authored image minus one. OP3FT Frogans Technology [Page 37] FSDL 3.0 Preliminary Draft #1 September 2015 6.12. Adding Layers to the Frogans Slide - Element The element defines a layer to be added to the Frogans slide. The element is a child either of the element (see Section 6.1) or of a