Director 7: Vector Shapes

April 26, 1999
by Will Turnage

In Director 7, Macromedia finally adds the vector shape as a native media type providing users with a low bandwidth way to include lines, shapes, and curves in their Director projects.

The biggest advantage for using vector shapes is that all of the information about the vector is stored mathematically, unlike bitmaps where color information is retained about each pixel. Since vector shapes are just equations and properties, the computer can use that information to draw the vector at any size, without losing quality.

To use vector shapes in Director 7, you must have the Shape Xtra installed for use in authoring. To use vector shapes with a projector, you need to include the Flash Asset Xtra. Both of these come packaged with Director 7 and are completely free.

Creating Vector Shapes

To create a new vector shape, simply open the vector window, or select Insert -> Media Element -> Vector Shape from the menu.

You can use either the pen tool to draw your own vector shape or you can use one of the three shapes Director provides for you: rectangle, rounded rectangle, or ellipse. When drawing with one of these three shapes, simply click and drag the mouse to whatever size shape you want. Holding down the SHIFT key while dragging will change your rectangle or ellipse into a square or circle.

Drawing with the pen tool is as easy as point and click. If you simply click the mouse, it will create a point without any control handles, also known as a corner point. However, if you want your shape to have curved, soft edges instead of sharp, pointed edges, you should click and drag the mouse. When you drag the mouse, you'll notice a line that appears through the middle of your vertex point. As you move this line, it changes the shape of your curve. The two ends of this lines are known as control handles since they control the shape of your curve.

If you want to change any points you've already created in your vector shape, you can just click on either the vertex point or the control handle, and move it around with the mouse. If you want to eliminate an existing control handle, click on it and drag it on top of its vertex point. If there are no control handles for a vertex point and you want to create one, simply option-click or alt-click on the vertex point and drag.

Importing Vector Shapes

What if you want to use existing artwork, or need more accurate drawing tools than those in Director? There is a solution, but first you have to understand Director's limitations with vector shapes and decide if vector shapes are the most appropriate solution. The biggest limitation is that each vector shape can only be ONE continuous curve. Multiple shapes and groups within one vector shape cast member are not supported.

If your artwork meets these requirements, then you can use Darrel Plant's PostScript to Vector Shape Converter to import your existing artwork into Director. The current version reads Adobe Illustrator EPS and AI files and converts them to Director 7 #vectorShapes. Before using this Xtra, please keep in mind the following notes from Darrel.

Each path in the Illustrator EPS is converted to a separate vector shape
Compound paths are not supported (only 1 path per VS)
Object text (not converted to outlines) is not supported
Only the raw shape data is converted, fill and stroke settings are not converted
Relative positions between paths are not maintained
Preview of created shapes in the VS window appears squashed horizontally, although points are drawn correctly
Making a slight modification to any point, then executing an Undo will force corrected update of preview and rect
Rect of created shapes is much larger than actual shape data

Using the Xtra is very straight forward. After downloading the movie, simply unstuff it and place the movie in your Xtras folder. After restarting Director, you will now see "ps2vs" in your Xtras menu. When you select this option, it will launch the Xtra.

Once the Xtra launches, click the Import EPS button and select your EPS or AI file. The Xtra will then process the file and create a new vector shape for each path in your file. I tested the Xtra by creating some text in Flash and then converting it to outline format by selecting Modify -> Break Apart. Next, I exported the image as an Adobe Illustrator file, and imported that file using the ps2vs Xtra. The process took less than a minute, and worked amazingly well. (As a side note, Darrel has made all of the code for this Xtra available for those who are interested in how he parses the AI files)

Altering the Look of a Vector Shape

Now that you've created the path for your vector shape, let's give it some color. For basic vector shapes, there are three lingo properties that can be set for each lingo shape. They are:

backgroundColor - an RGB color representing the entire background of your vector shape
strokeColor - the RGB color of the path (or line) of your vector shape
strokeWidth - a real number between 0 and 100 for the width of the path of your vector shape

So your lingo code for a cast member called "myVector" might look like the following:

on resetMyShape me
        member("myVector").backgroundColor = rgb(23, 34, 45)
        member("myVector").strokeColor = rgb(#FC23AA)
        member("myVector").strokeWidth = 23.456
    
end

Note: Director 7 uses a new RGB color model for selecting color. As shown in the above example, you can either specify numeric values for red, green, and blue, or you can use the hex format.

The next option for your vector shape is whether you want it open or closed. In the vector window, you can do this by clicking the closed checkbox, or via Lingo you can set the vector shape's closed property to TRUE or FALSE. If your vector shape is closed, then you have the added option of filling your shape one of three ways. You can have no fill, you can use a solid color, or you can use a gradient. This is done in the vector window by selecting one of these three buttons.

This can also be done in Lingo by setting the fillMode property of your vector shape equal to #none, #solid, or #gradient.

If you set the fillMode equal to #solid, then you can set the color of the solid fill using the fillColor property.

If you set the fillMode equal to #gradient, then you have seven different properties to determine how your gradient appears. Again, all of these properties are available in the vector window, or you can manipulate each one individually via Lingo.

gradientType - a property that can be set to #linear or #radial
fillColor - a RGB color that represents the starting color in the gradient
endColor - a RGB color that represents the ending color in the gradient
fillCycles - an integer between 1 and 7 that tells how many times the gradient repeats inside the vector shape
fillDirection - a float for the number of degrees the gradient is rotated
fillOffset - a point representing the relative distance from the center of the vector shape's rect that will act as the center of the gradient
fillScale - referred in the Vector window as "spread", this property is a float representing the percentage of a vector's interior that is filled with the gradient.

Changing the Shape through Lingo

If you need to change the curves in your vector shape during authoring, it's as easy as opening the vector shape window and moving around a few points with the mouse. But to change a vector's shape at run time, you'll have to use the vertexList.

The heart of a vector's shape is the vertexList. The vertexList is a linear list with its element representing sequential points along the curve. For instance, the vertexList of an ellipse might look like this:


[[#vertex: point(-86.0000, -25.0000), #handle1: ¬
  point(47.8800, -13.7200), #handle2: point(-47.8800, ¬
  13.7200)], [#vertex: point(85.0000, -25.0000), #handle1: ¬
  point(47.8800, 13.7200), #handle2: point(-47.8800, ¬
  -13.7200)], [#vertex: point(85.0000, 24.0000), #handle1: ¬
  point(-47.8800, 13.7200), #handle2: point(47.8800, ¬
  -13.7200)], [#vertex: point(-86.0000, 24.0000), #handle1: ¬
  point(-47.8800, -13.7200), #handle2: point(47.8800, 13.7200)]]

If you look closely at the vertexList, you'll see that each element in the list is represented by a property list containing three different properties: #vertex, #handle1, and #handle2. #vertex is a point that describes that point's relative location to the vector shape's originPoint*, and #handle1 and #handle2 are points describing each handle's relative distance from the vertex point.

* Note: Unlike bitmaps which use their registration point as the center of scaling and rotation, vector shapes use the originPoint as their center of scaling and rotation. By default, the originPoint is set to be the center of the vector shape. However, if you wish to change the originPoint, you first have to set the vector shape's originMode property. The originMode can be set to #center, #topleft, or #point. If you set the originMode equal to #point, then you can assign a specific point value to the originPoint property.

There are two ways to change the vertexList in Lingo. You can either manipulate the vertexList directly, or you can use one of Director's four built in handlers for changing the vertexList. They are:

addVertex - adds a vertex point and handles at a specific place inside the vertexList
deleteVertex - deletes a specific vertex point and its handles from the vertexList
moveVertex - moves a specific vertex point a relative distance from its current location
moveVertexHandle - moves a specific handle a relative distance from its current location

It's been pointed out in Bruce Epstein's new Director in a Nutshell that in Director 7, the addVertex() function is a little buggy. The function ignores the first handle you pass, and then assigns the second handle you pass to the first handle, leaving the new second handle equal to point(0,0). Until a fix is issued you can use this handler to create new points along a curve.


on addNewVertex, memberRef, indexToAddAt, pointToAddVertex, ¬
  handle1Point, handle2Point
  
   addVertex, member(memberRef), indexToAddAt, pointToAddVertex, ¬
     handle1Point, handle2Point
   member(memberRef).vertexList[indexToAddAt] = [#vertex: ¬
     pointToAddVertex, #handle1: handle1Point, #handle2: handle2Point]
     
end

Vector Playback Performance

The benefits of vector shapes are numerous, but their downside is the burden it can place on your processor. Since vector shapes are just mathematical equations, your processor has to re-compute the equations and render your shape on screen anytime your vector moves or changes shape.

To demonstrate vector performance, I created a test movie that contained a varied number of vector shapes moving one pixel at a time in any directon. All tests were run on a 200mhz MMX Pentium running at 1024x768 in 16-bit color (the Director projector was 640x480). The goal was to determine the maximum frame rate at which the Director movie could operate.

Number of moving vector shapes on screen (background transparent ink)	Fastest Frame Rate Achieved
1	156 fps
5	35 fps
10	18 fps
20	10 fps
40	5 fps

You can see from these results that vector shapes are capable of performing extremely well when only a few elements on screen are moving at a time, but when you start moving more than 10 around at a time, performance can suffer.

Summary

Whether you're creating your vector shapes in the new Vector drawing window or manipulating them with Lingo, I think you'll all agree that Vectors are a welcome addition to our favorite authoring program. By understanding the capabilities and limitations, you should be able to successfully integrate them into the design of your programs.

Will Turnage is a multimedia programmer based in New York City. In addition to his weekly role as Director Online's Multimedia Handyman, he is also the Technology Director for Sony Music's Client Side Technologies Group. You can read more about his work at http://will.turnage.com/.