Request nesting and embedding

Image Serving supports unlimited nesting of Image Serving requests, embedding of Image Rendering requests, as well as embedding images retrieved from foreign servers. Only layer images and layer masks support these mechanisms.

Nested Image Serving requests

An entire Image Serving request can be used as a layer source by specifying it in the src= (or mask=) command using the following syntax:

…&src=is( nestedRequest)&…

The is token is case-sensitive.

The nested request must not include the server root path (typically http:// *server*/is/image/').

Preprocessing rules are applied to nested requests.

The following commands are ignored when specified in nested requests (either in the request URL or in catalog::Modifier or catalog::PostModifier):

• fmt=
• qlt=
• iccEmbed=
• printRes=
• quantize=
• req=
• bgc=

If the result image of the nested requests includes mask (alpha) data, it is passed to the embedding layer as the layer mask.

Also ignored are attribute::MaxPixand attribute::DefaultPix of the image catalog that applies to the nested request.

The image result of a nested IS request can be cached optionally by including cache=on. By default, caching of intermediate data is disabled. Caching should be enabled only when the intermediate image is expected to be reused in a different request within a reasonable time period. Standard server-side cache management applies. Data is cached in a lossless format.

Embedded Image Render requests

When Dynamic Media Image Rendering is enabled on the server, render requests can be used as layer sources by specifying them in src= (or mask=) command. Use the following syntax:

…&src=ir( *renderRequest*)&…

The ir token is case-sensitive.

renderRequest is the usual Image Rendering request, excluding the HTTP root path http:// *server*/ir/render/.

The following Image Rendering commands are ignored when specified in nested requests:

• fmt=
• qlt=
• icc=
• iccEmbed=
• printRes=
• req=

Also ignored are attribute::MaxPix and attribute::DefaultPix of the material catalog that applies to the nested render request.

The image result of a nested IR request can be cached optionally by including cache=on. By default, caching of intermediate data is disabled. Caching should be enabled only when the intermediate image is expected to be reused in a different request within a reasonable time period. Standard server-side cache management applies. Data is cached in a lossless format.

Embedded FXG render requests

When the FXG graphics renderer (aka AGMServer) is installed and enabled with Image Serving, FXG requests can be used as layer sources by specifying them in src= (or mask=) commands. Use the following syntax:

…&src=fxg( renderRequest)&…

The fxg token is case-sensitive.

renderRequest is the usual FXG render request, excluding the HTTP root path http:// *server*/agm/render/.

The following FXG commands are ignored when specified in nested requests:

• fmt=
• qlt=
• icc=
• iccEmbed=
• cache=

Foreign image sources

Image Serving supports access to source images on foreign HTTP servers.

To specify a foreign URL for a src= or a mask= command, delimit the foreign URL or URL fragment with parentheses:

…&src=( foreignUrl)&…

Important The delimiter characters ( '(',')') and the command delimiter characters ( '?', '&', '=') within nested requests must not be HTTP-encoded. Effectively, embedded requests must be encoded the same as the outer (embedding) request.

Full absolute URLs (if attribute::AllowDirectUrls is set), and URLs relative to attribute::RootUrl are permitted. An error occurs if an absolute URL is embedded and attribute:: AllowDirectUrls is 0, or if a relative URL is specified and attribute::RootUrl is empty.

While foreign URLs cannot be specified directly in the path component of the request URL, it is possible to set up a preprocessing rule to permit conversion of relative paths to absolute URLs (see the example below).

Foreign images are cached by the server according to the caching headers included with the HTTP response. If neither an ETag nor a Last-Modified HTTP response header is present, the response is not cached. This can cause poor performance for repeat accesses for the same foreign image, as Image Serving needs to re-fetch and revalidate the image on every access.

This mechanism supports the same image file formats which are supported by the Image Convert (IC) utility, with the exception of source images with 16 bits per component.

Restrictions

The size of the image generated by nested/embedded requests is normally optimized automatically. If caching of nested request images is enabled, incremental performance gains may be achieved by specifying the exact size of the nested image, so that no further scaling is required when the cache entry is reused.

Important Image Serving does not support double-encoding of nested or embedded requests. Nested and embedded requests must be HTTP-encoded just like simple requests.

Examples

Layering template with caching:

Use nesting to add caching to a layering template. A limited number of background images are overlaid with highly variable text. The initial template string might look like this:

layer=0&src=$img$&size=300,300&layer=1&text=$txt$

With slight modifications, we can pre-scale the layer 0 image and cache it persistently, thereby reducing server load:

layer=0&src=is(?src=$img$&size=300,300&cache=on)&layer=1&text=$txt$

Embedding requests for Dynamic Media Image Rendering

Using a template stored in myCatalog/myTemplate; generate the image for layer2 of the template using Dynamic Media Image Rendering:

http://server/is/image/myCatalog/myTemplate?layer=2&src=ir(myRenderCatalog/myRenderObject?id=myIdValue&sel=group&src=is(myCatalog/myTexture1?res=30)&res=30)&wid=300

Note the nested curly braces. The Image Rendering request embeds a call back to Image Serving to retrieve a repeatable texture.

See also

src= , mask=, Request PreProcessing, Image Rendering Reference, Templates, Image Serving Utilities