Graphics and Rendering (2025)

Graphics and Rendering

In addition, documentation on the interface for input devices such as the joystick controller can be found in the API Reference Manual; see

.

The superpackage

includes the various packages that make up the graphics APIs, and gives your applet access to most of the commonly used features of the Curl language graphics system. These features include the 2D and 3D rendering systems and a library of image filters.

is imported as part of

, which is imported automatically when the Curl runtime encounters the {curl ... applet} herald in applet source code.

If you are using the {curl ... package} herald to create a package rather than an applet, CURL.GUI.STANDARD is not automatically loaded when the package is compiled. To include the GUI and graphics functionality in a package, import statement

explicitly:

Note: If you would rather import only the specific packages that your applet requires, such as

, be aware that there are many dependencies between the packages in CURL.GUI.STANDARD.

A texture is an infinitely thin surface, expressing a pattern or a solid color, which serves as a source object in any rendering process. Textures can be represented by the abstract base classes

and

, where:

Textures can be applied to surfaces in two ways:

• A texture can be stretched onto a surface; you can think of it as a stretchy picture.
• A texture can be repeated on a surface; you can think of it as a set of tiles.

There are two general ways of creating a

:

The argument convertibleobject must be an object of one of the following types:

• Pixmap
• Texture (of which Color is a subclass.)
• Drawable

  This is a relatively uncommon way to create FillPatterns and it is normally done using an offscreen Drawable in conjunction with Image Filters.

• A StringInterface representing a color string for a solid color. See the From Solid Colors section for more information on using solid colors.
• A Url representing an image file. See the From Image Files section for more information on using image files.

Textures that are solid colors are represented by the

class, which is a subclass of Texture. There is no equivalent in the FillPattern class hierarchy, because FillPattern is able to convert any Texture, including Color. Therefore, you need not be concerned with the details of the Color class to be able to set the color of graphical objects and text.

Most of the color-related properties of graphical objects and text are represented by options whose type is FillPattern. To apply a uniform texture to these objects, set their relevant options to any of the following ways, and FillPattern will perform the conversion:

• A Color object. (For example, the Color.from-rgb procedure returns a Color object.)
• A String in the form:

  "#rrggbb"

  where rr, gg, and bb are pairs of hexadecimal digits specifying the red, green, and blue color intensities, respectively.
• A String naming one of the supported color names. See Supported Color Names for the list of supported color names.
• For standard colors, it is more efficient to use the procedure FillPattern.get-<color>, where <color> is one of the supported color names.

For example, you can set the option color (see

) to any supported color name, because its type is FillPattern. For text, you can use the color= keyword argument syntax, as shown in the following example. The colors of the frames are set using the other techniques outlined above:

To create a FillPattern from an image file, you simply specify the file as a

object.

The basic syntax for doing so is:

 {url url-string}

where url-string specifies, in double-quotes, the location of the image file, using url format. The quotes enclose the path and name of an image file whose format is supported. See Image File Formats for the supported image file formats. The contents of the image file are converted to a FillPattern.

Because you can easily convert an image file to a FillPattern, you can supply it as a value for any parameter that requires a FillPattern object. The example below shows the effects of setting the background property of a graphical object, such as

:

The previous section shows how a

can be automatically created from a

,

,

, or image file. You can also convert from FillPattern to Pixmap, Texture, or Drawable. You should plan you application to avoid unnecessary conversions.

The

class encapsulates information that describes the environment in which a FillPattern will be used. Standard hints are usually provided when a FillPattern is applied to a graphical object. The standard hints are:

• width
• height
• resolution

The standard hints are also properties of the FillPatternHints class. To create a FillPatternHints object, call

and supply the hints.

If you are writing your own FillPattern subclass and are implementing the to-* methods, you can use another property,

, to verify whether the caller has provided standard hints before you attempt to get them.

In addition, your implementation of these methods can expect and make use of its own hints, not just the standard hints.

• The implementation of a subclass's to-* method can get the value of a hint by calling FillPatternHints.get and providing the hint's key as a string.
• When calling such a class's to-* method, you can supply the non-standard hints by:
  1. calling FillPatternHints.create#factory, and
  2. supplying the non-standard hints by entering them as key = value keyword arguments.
  Doing so creates a FillPatternHints object with non-standard hints.

Any number and combination of standard and non-standard hints may be supplied.

You can modify a FillPattern by using the

macro, which requires you to provide a FillPattern and specify the class you would like to use to operate on the FillPattern. This class must be one of:

The following example:

1. creates a FillPattern from an image file,
2. mutates the FillPattern with the mutate-fill-pattern macro, using a Pixmap method that inverts an image,
3. uses the mutated FillPattern as the background of a Fill graphical object.

A FillPattern may be readable and/or writable, as indicated by its

and

properties.

• If a FillPattern is writable, you can mutate it by calling the mutate-fill-pattern macro, which allows you to work on it using a Drawable or Pixmap interface.

  For example, the image filters of the graphics system operate on FillPatterns, which serve as source and destination.

• If a FillPattern is readable, as most are, you can call its to-* methods (such as to-Texture or to-Pixmap), which read from the FillPattern and return an instance of the specified type of object.

A subclass of FillPattern is the

class. This class is abstract. It represents a FillPattern that is based on Pixmaps, and therefore has an underlying Pixmap. If you are writing your own subclasses, you can subclass from FillPattern or from PixmapBasedFillPattern.

In subsequent calls, it may re-create and/or resize the underlying Pixmap so that the returned Pixmap is a new object. In modifying the underlying Pixmap, this method also creates the underlying

such that a call to to-Texture on the FillPattern returns the underlying Texture.

Two implemented subclasses of PixmapBasedFillPattern are

and

. They are examples of procedural FillPatterns, which generate their images from code rather than pixels, and therefore reduce download. These FillPatterns are readable but not writable.

Their implementations of

compute the values of the elements in the underlying pixmap. Both use

to iterate over the pixmap.

To write your own procedural FillPattern, you should also subclass PixmapBasedFillPattern and override the following methods:

• The constructor
• The PixmapBasedFillPattern.clone-from constructor
• PixmapBasedFillPattern.compute-pixmap
• PixmapBasedFillPattern.to-Pixel

FillPatterns are often applied to certain properties of graphical objects. For example, the graphical option background takes a FillPattern. You can supply either a FillPattern object or any object that can be converted to a FillPattern, including a

object, which is a Texture.

Sometimes it is desirable to have a "stretchy" picture that sizes itself to fill available space. Although you can do this by creating custom

s for the width and height properties of an

object, this approach has some drawbacks. Notably, there is no way to express the constraint of an aspect ratio in the Curl language layout system.

There are two ways to tile the surface of a graphical object. One is to tile a FillPattern by using the

method. If the difference between the uv1 and uv2 parameters is greater than 1, the image represented by the color parameter repeats. The number of tiles is determined by the difference between uv1 and uv2, and the offset of the tiles within the image is determined by the value of uv1. Try setting different values for uv1 and uv2 in the following example:

Another way of achieving the same effect is to use the

factory.

is a wrapper for

s that can be used to simplify certain tasks. Here is the same image, in this case a

tiled via this approach. Notice that you can specify the tile size, if it is not the same as the size of the input image, as well as the total size of the area to be tiled. The pattern parameter is a FillPattern.

The

class is very similar to the

class; both represent images, and they are created in similar ways. However, Texture is a lower-level class, and is used with lower-level interfaces. FillPattern is mutable (via the

mechanism), whereas Texture is immutable; once you have a Texture object, you cannot change its contents. Note, however, that you always have the option of creating a new Texture object and throwing the old one away.

FillPattern is generally used with higher-level interfaces, such as the Curl® GUI Toolkit, the Scene package (for 3D retained-mode rendering), and the

interface. Texture is generally used with lower-level interfaces, such as

, which is commonly used to do immediate-mode 3D rendering.

Finally, as with FillPatterns, you can easily access the built-in colors by obtaining an existing Texture object. This is done via the methods of the

class, such as

. A complete list of the color names you can use this way is shown in Supported Color Names.

One way to work on textures is through the Pixmap interface. The

class represents a two-dimensional array of

s, each holding red, green, blue, and alpha values.

A

is a 2D array of pixels. Its width and height represent the number of pixels in each of those dimensions. There are two ways of referencing the pixels of a pixmap:

• The 2D addressing scheme requires two coordinates. The upper-left pixel is pixel (0, 0), and the lower-right pixel is (Pixmap.width - 1, Pixmap.height - 1).
• The 1D addressing scheme requires an index value. You can think of the pixmap as a one-dimensional array of pixels, where the first element is the upper-left pixel, the subsequent elements follow from left to right, proceeding from the top row to the bottom row. The last element in the 1D array is the lower-right pixel in the pixmap.

For example,

sets the specified pixel to a value. You specify the pixel by using the 1D addressing scheme.

The Pixmap class has three properties that serve as helper properties to accommodate these two addressing schemes.

• Pixmap.max-x and Pixmap.max-y return the pixmap's width - 1 and height - 1 respectively. Use them as appropriate in 2D addressing to reference edge pixels.
• Pixmap.max-offset returns the index of the last pixel in the 1D addressing scheme.

To set a particular element in a pixmap, use the

method, and provide a

as the value.

To set a range of elements in a pixmap, use

, which iterates over the elements of a pixmap, allowing you to set the ones you want.

Each of the image filters provided in the

package is a procedure that takes a source FillPattern and returns a (different) processed FillPattern. See the Image Filters chapter for information on them.

If you choose, instead, to work with Pixmaps, use the

procedure to wrap the image filter procedure.

For example, if you want to use the

procedure on the image shown in the previous example, wrap it in filter-pixmap as follows:

You can distort a texture using the

class.

If you use the

method to perform a distortion, one of the arguments is a DisplacementMesh object describing the distortion. To specify a distortion, you set the desired grid points to new locations. Calling

sets each specified grid point to the specified location.

Copyright © 1998-2019 SCSK Corporation. All rights reserved.
Curl, the Curl logo, Surge, and the Surge logo are trademarks of SCSK Corporation. that are registered in the United States. Surge Lab, the Surge Lab logo, and the Surge Lab Visual Layout Editor (VLE) logo are trademarks of SCSK Corporation.