SVG Size, Bounds and Flat

The SVG (Scalable Vector Graphics) format document may or may not have a size. If a document has a size, it is stored in the width and height attributes of the root svg element and can be in any coordinate system. An SVG renderer will typically use this value to determine the final bounding rectangle of the document. If it is omitted, it will require this information to be supplied externally (for example, using the parent container of the SVG). A unit of measurement is also required to convert all coordinate system to physical pixels. This is called the viewport of the document.

SVG documents contain a hierarchy of elements. The final transformation (such as position and size) and style (such as color and fill) may depend on the transformation and style of the parent(s) inside the hierarchy. An SVG renderer has to calculate and keep track of this information when outputting the document to a device for viewing. This procedure is defined by LEADTOOLS as flattening the document. A document that does not have the transformation/styles applied to the child elements is defined as non-flat document by LEADTOOLS. A document that has the transformation/styles applied to the child elements is defined as a flat document by LEADTOOLS.

Therefore, to render an SVG document, the following steps are usually performed:

• The document is flattened so that each child element has its final transformation/style applied.
• The viewport is used to place or render each element into its final position and size.

SVG Document Support

LEADTOOLS can handle any type of SVG (with or without a size, whether it is flat or non-flat). However, to render the document or to extract final element position and size, any missing information must be either calculated automatically or supplied by the user.

To convert a non-flat document to flat use L_SvgFlatDocument. This function accepts a parameter of type L_SvgFlatOptions that contains the final desired size of the document in pixels. If this parameter is omitted or the value of the size is 0, then LEADTOOLS will try calculate the final size automatically. When this method returns, all of the transformation and style values will be applied to each child element.

To determine whether a document is flat, use L_SvgIsFlatDocument. This as an internal state saved by the class and will be FALSE if L_SvgFlatDocument has not been called on the document previously. L_SvgSetFlatDocument can be used to set or reset the state of this flag manually if desired.

The size and final viewport of a flat SVG document can be calculated using L_SvgCalculateBounds. This function will use the current size information (if available) plus the physical position, size and transformation of each element to compute the final size in pixels and the resolution of the document. To get the bounds, use L_SvgGetBounds.

L_SvgCalculateBounds accepts a Boolean value that controls whether to ignore the current size information if available and purely use the child element's position and size (trimmed) or use the size if available (non-trimmed). L_SvgCalculateBounds will fail if the document is not flat.

To determine whether the size of the document has been calculated, use the L_SvgBounds.IsValid. This is an internal state saved by this class and will be FALSE if L_SvgCalculateBounds has not been called on the document previously. L_SvgBounds.Bounds and L_SvgBounds.Resolution contain the physical bounding rectangle in pixels and the resolution in DPI of the document respectively. L_SvgSetBounds can be used to set or reset the bounds manually if desired.

When loading an SVG document directly using L_SvgLoadDocument or L_SvgLoadDocumentMemory, no flattening or calculating of size will take place. The document is loaded as is.

When using L_LoadSvg to convert a page from any document or vector to SVG the resulting document may or may not contain size, bounds or flat information.

L_SvgRenderDocument is used to render an SVG document to a target device. This method requires a flat document with valid bounds. For more information, refer to SVG Rendering.

The following code illustrates how to render a document by automatically checking and flat and bounds state:

void RenderDocument(L_SvgNodeHandle docHandle, HDC hdc, L_SvgRenderOptions* options) 
{ 
   L_SvgNodeHandle flatDocHandle = NULL; 
   // If the document is non-flat, flatten it, automatically calculating the size 
   L_BOOL isFlat = TRUE; 
   L_INT nRet = L_SvgIsFlatDocument(docHandle, &isFlat); 
   if (!isFlat) 
      L_SvgFlatDocument(docHandle, &flatDocHandle, NULL); 
   else 
      flatDocHandle = docHandle; 
   // If the document does not have a valid bounds, calculate it now, automatically 
   L_SvgBounds bounds; 
   L_SvgGetBounds(flatDocHandle, &bounds, sizeof(L_SvgBounds)); 
   if (!bounds.IsValid) 
      L_SvgCalculateBounds(flatDocHandle, FALSE); 
   // Now, render the document 
   L_SvgRenderDocument(hdc, flatDocHandle, options); 
   if(!isFlat) 
      L_SvgFreeNode(flatDocHandle); 
}