-------------------------------------------------------------------------------

                 A C 3 D   X - P L A N E   P L U G I N

The X-Plane import/export plugin for AC3D adds extra functionality
that supports the reading of X-Plane Object version 7-8 files.  These 
files should be compatible with all versions of X-Plane  (although some 
features are only supported in version 7.40 and beyond for OBJ7 and 8.20
and beyond for OBJ8).

This plugin provides both import and export of X-Plane Object 7/8 files into
and out of AC3D, and also a few useful commands for working with Objects.

See below for installation instructions and other details.

-------------------------------------------------------------------------------
CHANGE HISTORY:
-------------------------------------------------------------------------------
KNOWN BUGS:
	- OBJ7 import/export does not handle panel tex quads or hard quads.
	- Ac3d texture repeat/offset cannot be used with panel textures for exporting.



Nov 2022
added lit_nits value to attr_light Load and saves OK. Loads an old format file and sets default to 1000.
added a default value function alternative for float attributes FLT_PROP_DEF for nits. This means that if this value is requested from
an object and it has not yet been defined, the default value will be returned.
obj_model.cpp holds the defaults. v2 made to have default of 1.0f








Version 4.0b0
	- updated for XP12 (require AC3D 9 min)
		extra _bb and _pm lights added
		added lit_nits (brightness) value to attr_light (default 1000)
		light parameter labels are updated with correct field labels (from the data in lights.txt)
		The number of max selected objects/panels open at once can be increased up to 9 (not larger) by editing MAX_SEL in the tcl file.
		light-type popup menu changed to a more compact combobox.
		dref pulldowns have been made longer
		"cd" value in lights now imported and exported correctly




Version 3.5b3
	- requires AC3D 9.0 minimum
	- changed "X-Plane Properties" window to use new_toplevel_document_tracked instead of new_toplevel_tracked (For Mac)
	- updated to use get_full_plugin_file_path command from AC3D 9 to find the location of datarefs and commands.txt files
	- fixed get_data in bitmap_match source - was reading int for image data, rather than addr 64 bit fix

Version 3.5b2 (not public release - internal use only)
	- requires AC3D 8.7 minimum
	- the OBJ file text header (from XPlane-export-settings dialog) can now contain %f and %b. 
		These will be replaced by the filename and basename respectively
		e.g. for filename myplane.obj, "TEXTURE_LIT %b_lit.png" becomes "TEXTURE_LIT myplane_lit.png"
	- fixed bug getting AC3D image address
	- fixed glass_blending and use_metalness were not initialized in new obj8 object new defaults glass_blending=0, use_metalness=1
Version 3.5b1
	- an OBJ file text header can be now edited in XPlane-export-settings dialog.
	     The text is inserted at start of every exported obj file (just after the OBJ file header).
	     Default value is "GLOBAL_specular 1.0\n" (newlines can be added with "\n")
Version 3.4b4
	- fixed - additional float params after light x,y,z are now loaded
Version 3.4b3
	- Tcl/TK (UI) removed Tcl variable trace (caused infinite update loop)
Version 3.4b2
	- fixed problem with TEXURE_NORMAL output	
Version 3.4b1
	- moved to 64 bit
	- added quotes around call to sync_dref - handles blank names
	- added check for anim_end without corresponding anim_begin in obj8 loader (crashed with some bad files on Linux)
	- switched off the ---- tearoff menu item from popup menus
	- added magnet to light options
	- added 1110 Manipulators: rotate axis-detent command-knob-2way command-switch-up/down-2way command-switch-left/right-2way
Version 3.3b3
	- fixed divide by error caused by compilation bug
Version 3.3b2
	- added option to export TEXURE_NORMAL line with filename based on the texture name with _normal inserted
Version 3.3b1
    	- support for all 1050 manipulators in ac3d and obj code.
Version 3.2.1r2
	- Panel export works with Panel_general.png naming convention.
	- Dataref.txt parsing isn't fooled by quoted strings.
Version 3.2r1
	- No changes, relabel to final.
Version 3.2b5
	- Fix to panel region exports with heavily modified manipulator settings.
Version 3.2b4
	- New manipulators for 930b13
Version 3.2b3
	- LIT level commands are scaled.
	- Fixed manipulator import.
	- Added automatic manipulator axis detection
Version 3.2b2
	- ATTR_light_level syntax adjusted fto stay in sync with X-Plane.
	- Panel region export fixed.
Version 3.2b1	
	- Panel_preview textures are supported
	- Plugin will find the panel texture in a much wider range of locations,
	  including the 3-d cockpit.
	- Animation sliders can be set to only show animation for visible geometry
	- Support for OBJ syntax from X-Plane 921 and 930
	- Bug fix: importer produces less vertices.
	- Bug fix: line endings on Windows fixed
	- Bug fix: panel region doesn't have decimal at end.
	- Bug fix: no error message if you pop open dataref menu when datarefs.txt not in plugin folder.
Version 3.1r1
	- Support for ATTR_hard_deck
	- Bug fix in importing hard surfaces!
	- Compatibility with AC3D 6.3
Version 3.1b1
	- Animation is faster
	- Key Frames
	- Sub-Panel Interface
	- Select all animation button
	- Select all lights menu command
Version 3.0.2
	- Update old object updates lights
	- Bulk update command
	- Better optimization of rotate animations
Version 3.0.1r1 9/20/07
	- As an optimization, the OBJ8 exporter no longer writes the unnecessary ATTR_shade_flat
Version 3.0r1 9/17/07
	- This is a rename of 3.0b3 with latest code.
Version 3.0b3 6/25/07
	- Optimization utils
	- Animation window scrolls
	- LOD group name label was wrong in property editor
	- Objects can be renamed directly in the X-Plane Properties Editor
Version 3.0b2 5/15/07
	- Prefix can be provided for texture export.
	- Workspace can be epxorted by texture.
	- Textures can be reloaded.
	- Bug fix: texture paths fixed.
	- Bug fix: object properties can be edited in vertex mode.
	- Bug fix: precision of numeric fields limited.
	- Bug fix: TEXTURE_LIT not written if there is no _LIT.png on disk.
	- Bug fix: show/hide animation can be previewed.
Version 3.0b1 8/15/06
	- Total rewrite of how x-plane properties are managed
	- Previev of animation
	- Support for materials, smoke, named lights, custom lights, show/hide animation
Version 2.1b2 2/15/06
	- Fixed texture repeat-offset export (was ignored since 2.0).
Version 2.1b1 1/20/06
	- Reorganized attribute handling
	- New commands: group export, make trees, one-sided geometry, downward normals
	- Bug fix for crash on OS X 10.4.4 with QuickTime 7.0.4
Version 2.0b2 9/27/05
	- Bug fix for animation export.
Version 2.0b1 9/20/05
	- Pretty much a total rewrite of Obj I/O code for XP7.
	- Support of the annotation system for non-AC3D native properties.
	- Addition of the Animation-group command.
	- Supports light import/export

Version 1.1 11/30/04

	- Support for cockpit quads.
	- Bug fix: ATTR_nocull renamed to ATTR_no_cull
	- Bug fix: Objects are treated as smooth shaded by default.
	- Bug fix: Smooth shading and culling reset at the end of each LOD.
		(Note: this is only needed for older versions of x-plane.)
	

-------------------------------------------------------------------------------
INSTALLING
-------------------------------------------------------------------------------

Simply copy the AC3D plugin file XPlaneSupportWin.p or XPlaneSupportMac.p
(depending on your operating system) and the file XPlaneSupport.tcl into
the "plugins" folder for AC3D while it is not running, then start AC3D.

NOTE FOR MAC USERS: For AC3D 8.5 and later, plugins and other support files
should preferably be installed in:
    ~/Library/Application Support/com.inivis.ac3d/plugins 
This removes the need for users to open up the App bundle to find the plugin
folder.

The plugin also requires two text files: DataRefs.txt and Commands.txt - these are
computer-readable lists of X-Plane's current datarefs and commands.  You can 
get them both from the Resources/plugins folder of X-Plane 930 and newer.

-------------------------------------------------------------------------------
USING THE PLUGIN
-------------------------------------------------------------------------------

When the plugin is installed the export menu gains two new options: 
"X-Plane 7 Object File..." and "X-Plane 8 Object File..." and the Import dialog
will have a file type "X-Plane 7/8 Objerct File (*.obj)" in it.  (Note: if you
have the Alias  Wavefront Object importer plugin installed this may not work.)

To import an object, simply choose import and select your .obj file.  It will
be imported and appear in the main windows.

To export an object, simply pick the export menu item for the version you want
to save and save your file.

-------------------------------------------------------------------------------
LIMITATIONS
-------------------------------------------------------------------------------

This importer/exporter does not support:

 - ATTR_no_depth (you shouldn't use it anyway!)
 - It will not build quad strips, tri strips, or tri fans for version 7 
   objects. (Please note that these are not supported in OBJ8.)
 - There is not yet a way to preview night lighting inside AC3D.
 - Movie quads (for OBJ7 - these are not supported in OBJ8.)
 - Ambient and specular materials (they do not work in X-Plane anyway).

Please note that the color of a line will be exported from the material in
AC3D.

WARNING: Importing and Exporting can lose information.  Your best bet is to
save your work in AC3D format (.ac) and export to OBJ; do not use OBJ as your
master format for editing, rather just as a final output format.

-------------------------------------------------------------------------------
TEXTURES AND AC3D
-------------------------------------------------------------------------------

Object 7 and 8 files can have only one texture; make sure you use the same 
texture for every object in your model.  The easiest way to do this is to 
select all objects via the Object Hierarchy window (click on 'World') and then
pick your texture from the Object->Texture submenu.

AC3D requires a plugin to read .png files; it can read .bmp files by default.

When an object file is loaded, the texture will be loaded if it is in the same
directory as the .obj file itself.

Textures are normally saved without any relative path information.  For 
example, if the texture file for my object is "jetway.bmp", only "jetway" is 
written to the OBJ7 file, and the texture must be in the same folder as the 
object (X-Plane 8) or the "Custom Object Textures" folder (X-Plane 7).

If you want to specify a texture in a subfolder for X-Plane, you can use the
"texture export prefix" setting (in the X-Plane export preferences).  You can
use a prefix that includes slashes to specify that textures belong in 
subfolders.

For X-Plane 7 users: Because this texture handling is different from X-plane's, 
you may want to keep textures with your objects until you are done editing your 
object, then move the bitmap or png file and change the path for your object 
when you are ready to package up the object in your custom scenery package.

-------------------------------------------------------------------------------
COCKPIT OBJECTS AND PANEL TEXTURES
-------------------------------------------------------------------------------

WARNING FOR EXISTING USERS: version 3.2 of the plugin has manipulator controls.
You must set your panel textured objects to be manipulatable or they will not
respond to the mouse in the sim!  This is a one time change you must make to
any .ac file when you adopt the new plugin!  See "Manipulators" below.

AC3D will let you use a panel texture to create a cockpit object with
instruments that animate.  To do this, you texture part of your object with
either the panel texture from your airplane or a panel preview texture.  Panel
textures are located in the cockpit/-PANELS- or cockpit_3d/-PANELS- folder.
(The plugin will not use an old-style panel file name from the root of your 
aircraft.  It also will not use BMP-based panels.  Don't use BMP!)

    my object.obj
    cockpit
      -PANELS-
        Panel.png
        
With this plugin you can also use a panel preview.  A panel preview is an
image of the panel textures for your object - not just the background, but
all of the instruments and moving parts too.  Panel previews have the name
Panel_Preview.png and live in the cockpit/-PANELS- or cockpit_3d/-PANELS-
folders.  You can make a panel preview in X-Plane 930 by pressing control-
option-shift-space with your airplane loaded.  The advantage of panel 
previews over the panel backgrounds is that they provide a better 
indication of what your finished panel will look like.

When you import an OBJ, the importer will first look for panel previews,
then panel backgrounds.

PERFORMANCE WARNING: changing between the panel and regular texture in an 
object hurts framerate; see the section on performance for how to avoid this
problem.

WARNING: for OBJ7 objects, you can only place the panel texture on quads.  AC3D
will warn you if you try to export an OBJ7 object that violates this rule.

In X-Plane 9 you can use up to 4 "regions" of your panel.  Using panel regions
instead of the whole panel switches X-Plane to use modern lighting on the panel
texture, and can sometimes improve peformance.

To set whether you are using the whole panel or regions, pick "X-Plane Panel
Properties..." from the X-Plane menu and check "Enable panel regions". You
can then set the number of regions and their coordinates (in pixels).

When you import an OBJ with a panel (or panel regions), the panel properties
will be readin from the imported object.  BUT the panel properties are saved
as a PREFERENCE, not as part of your .ac file (due to a limit in the ac3d
plugin system).  For this reason, be sure to reset your panel preferences 
when changing which airlane you work on.

WARNING: if you either have a texture map that goes outside a region or
a texture map that crosses two regions, the export may look corrupt in
X-plane.  Be sure that all of your UV maps are limited to only one region.

IMPORTANT: this limitation applies per _object_ in the AC3D hieararchy.
If you want to use two regions, use two objects in the ac3d hierarchy!!

For more information on panel regions: please see this page:

http://wiki.x-plane.com/Panel_Regions

The settings shown in the manipulator screen will vary depending on the type
of manpulator shown.  For manipulators that require a 3-d relative axis in
object space, a "guess" button will appear.  When you click this button, the
plugin will inspect the surrounding animations and attempt to choose a 
manipulation axis appropriate to match the animation.

The guess feature is not perfect and will sometimes be unable to guess or will
come up with wrong results.  For best results, set up your key frames and
dataref values (for both the key frame and the manipulator) before guessing.

-------------------------------------------------------------------------------
ONE-VS-TWO-SIDED GEOMETRY AND FLAT-VS-SMOOTH SHADING
-------------------------------------------------------------------------------
X-Plane objects are by default one-sided and smooth-shaded.  The 
importer/exporter correctly handles two-sided and smooth shaded objects in 
AC3D and OBJ7 files.  Warnings:

 - Two sided polygons are slower than one-sided polygons; only set a surface
   or object to be two-sided when it is necessary.  In particular, the cost of
   changing from one-sided to two-sided polygons is expensive.  It may be
   better to simply use one-sided polygons and duplicate any geometry that must
   be visible from both sides.

 - Smooth shading is not always smooth; the actual shading is a function of the
   3-d program.  But changing the shading model is slow, so it may be best to
   only use smooth sahding and use AC3D's crease-agnle function to tune the look
   of your object.  What you see in AC3D is what you will get with an OBJ8.
   
 - OBJ7 shading is always flat looking, regardless of AC3D look and shading
   settings.  Since OBJ7 shading cannot be changed, tune your object for its
   best OBJ8 look.
   
Also there are some serious performance considerations regarding these features
so be sure to read the PERFORMANCE section carefully before using them!

-------------------------------------------------------------------------------
EXPORT ORDER
-------------------------------------------------------------------------------

The AC3D exporter exports your object in the order that the hierarchy window
reads vertically.  In other words if your hierarchy window shows:

-World
    Group1
       Obj1
       Box
    Rect
    Group2
       Disk
    Sphere

Then the objects are exported in the order: Obj1, Box, Rect, Disk, Sphere.  The
order of your object is very important both for correct rendering of
translucent textures and for performance; see the PERFORMANCE section for more
info.  Use groups, objects, and the hiearchy window to control ordering.

-------------------------------------------------------------------------------
EDITING X-PLANE SPECIFIC PROPERTIES
-------------------------------------------------------------------------------

The X-Plane plugin adds a new menu, "X-Plane" to AC3D with X-Plane specific 
functionality.  The plugin also provides a way to edit properties of X-Plane
objects that are not supported directly by AC3D.

You can view and edit X-Plane specific properties using the "X-Plane Object
Properties..." command, which will show the X-Plane object inspector.  As you
select different objects, different options will be visible.

For any selection of up to 5 objects, you will see 5 sets of properties
horizontally in the inspector.  Click "apply to all" to edit all 5 at once.

If you have more than 5 objects of the same type selected, you will see one
property editor for the first object - you can use the "apply to all" button
to edit large numbers of objects at once.

If you have more than 5 objects of different kinds, the pane will simply
indicate "multiple objects selected".


-------------------------------------------------------------------------------
OBJECT ATTRIBUTES: HARD POLYGONS, POLYGON OFFSET, MATERIALS, ETC.
-------------------------------------------------------------------------------

For objects you can set the following properties.  Please note that object
properties can affect performance and can be complex - see the performance
section at the end of this document as well as the X-Plane scenery website.
For manipulations, see later in this document.

Polygon hardness

	Polygon hardness indicates whether the polygons of this object will 
	interact with X-Plane's physics model.  The default is "none" for
	no interaction.  By picking other hardnesses, you can make the surface
	be physically interactive and select what surface type the polygon
	acts like (e.g. grass, dirt, etc.).  The surface type "object" emulates
	the perfectly smooth surface that X-Plane 7 and 8 provided.
	
	For X-Plane 9, you can also mark a hard surface as a "deck".  If a hard
	surface is a deck, the user can fly under the hard surface and land on
	top of it.  If a hard surface is not a deck, the user can land on top of
	it, but attempting to travel under the deck will result in the plane
	crashing into the hard surface.
		
Polygon Offset

	Polygon offset can be set from 0 to 5 - use this to help polygons that
	overlap the terrain from Z-thrashing.
		
Blending

	X-Plane normally uses alpha blending to draw objects.  By unchecking 
	this option you can tell X-Plane to make the polygon either 100% opaque
	or transparent. 
	
	When blending is off, a cutoff level is shown - only pixels with more
	than this percentage opacity will be shown.
	
	Author-set blending cutoff levels are supported starting with X-Plane 850.
	
Materials

	Normally the X-Plane AC3D plugin does not generate material commands.
	However if you check this, then the current AC3D material will be exported
	as part of the object.
	
	Please note that the only aspects of the AC3D material that are supported
	are: the diffuse color, the emissive color, and the specular color (which
	is treated as gray-scale since X-Plane only supports specular hilighting,
	not setting the specular color in RGB).
	
Disable Drawing

	Normally an object is drawn.  By clicking "disable drawing" you can set
	an object to not be drawn but still be click tested, etc.  USe this to
	create "physics and mouse" only objects.  Note that unlike hide 
	animations (which hide an object for physics, drawing and clicking),
	checking "disable drawing" only affects drawing, but always takes effect!

	Draw Disable is supported in X-Plane 930 and higher.

Hard Walls

	For cockpit objects, check this box to make a triangle impassible to the
	3-d camera.  You can use this to keep the pilot from walking through the
	cockpit walls.  We recommend using draw-disable + wall to make a much
	simpler mesh to define the "constraints" of the cockpit.
	
	Hard walls are supported in X-Plane 930 and higher.

Dynamic _LIT Levels

	Normally the LIT texture is drawn at full brightness.  If this is checked,
	a dataref text field appears; you can enter a numeric dataref that will 
	set the brightness of the LIT level for this object.  The dataref must 
	return a value from 0 to 1.
	
	Lit level changes are a fairly expensive state change, so try to 
	consolidate similarly-lit objects whenever possible!
	
	Dynamic lit levels are supported in X-Plane 930 and higher.
	
	WARNING: dynamic light levels do not affect panel-textured or 
	panel-region-textured triangles.

-------------------------------------------------------------------------------
LIGHT ATTRIBUTES: LIGHTS AND SMOKE
-------------------------------------------------------------------------------

Point lights in AC3D are used for both lights and smoke generation points in
X-Plane.  When you select a light, a popup menu lets you edit what it is 
used for:

None

	If you set a light's type to "none" it will not be exported.  If you are
	using AC3D's lights to create real illumination effects (e.g. to simulate
	the sun and moon) use this to have the light be ignored.
	
Black Smoke, White Smoke

	These choices will cause the point light to be expored as a smoke-
	generation point.  You can set the puff size.
	
RGB

	This sets an RGB-style light.  The red, green, and blue values can be
	set from 0 to 1 (or a few special values - see the OBJ8 specification).
	
	(Note: it is better to use named lights to create special effects than
	to use special RGB values.  Please see below.)
	
Custom

	This creates a custom light animated by a dataref.  This is only useful
	for expert modelers - see the OBJ8 specification for the meaning of
	LIGHT_CUSTOM commands.
	
(All other choices)

	The rest of the choices in this menu are "named lights" - that is, premade
	light definitions that X-Plane knows how to create.  This is the best way
	to create lights, as X-Plane will use the best available rendering 
	technology to create the light.

-------------------------------------------------------------------------------
GROUPS: LEVEL OF DETAIL AND LAYER GROUPS
-------------------------------------------------------------------------------

When you select one of the top-most groups in an object, you will see the
"level of detail" parameters.  Use these to set the level of detail range
for a group.

If you leave the level of detail distances at 0 for each distance, then
no level of detail will be exported and X-Plane will select a level of detail
for you.

To get a feel for how this works, try importing the KSBD sample object.  Note
that after import, multiple versions of the object are visible; you may want 
to hide a version of the object (this can be done by right-clicking on an 
object in the hierarchy window and picking 'hide') to reduce clutter on the 
screen.

Groups can also have "layer group" information.  Layer groups are an advanced
concept - for more info, see the OBJ8 specification.

If you set a group to have a layer group other than "none", the plugin will
export an ATTR_layer_group attribute.  Please note that there can be only
one ATTR_layer_group for an entire object, so if you have conflicting layer
groups specified, the results will be inconsistent.

-------------------------------------------------------------------------------
ANIMATION
-------------------------------------------------------------------------------

Probably the biggest new feature in the AC3D plugin is animation.  Please read
this section carefully because animation support for the plugin has been 
completely rewritten.

Animation in an X-Plane object always happens inside an animation group.  An
animation group is represented by a group in AC3D that you create with the
"Make animation group" command.  Animations will only function when they are
inside an animation group.

You create animations using the commands in the X-Plane menu.  Animations are
represented in AC3D by lines - the meaning of these lines depends on the
type of animation.

- Translations: the line represents a relative movement in 3-d space.
- Rotations: the ilne represents the axis to rotate around.
- Show/hide: the animation line is just a placeholder.

Once you create an animation object, selecting it will show the animation
properties in the X-Plane property editor:

Low Value/High Value

	For a show/hide animation, this is the range that the dataref must
	be in to cause the object to appear or disappear.

Value 0..Value 1..Value N

	These are the values that the dataref must take on to map to the
	various key frames of the animation.
	
Angle 0..Angle 1..Angle N

	For rotations, this defines the angles to rotate for each dataref,
	mapped to each value.
	
Anchor

	For translations, this defines which point in the translation 
	(0, 1, 2, etc.) represents no movement of your model.  The default 
	is 0.
	
Dataref

	For any type of animation, this is the dataref to link to.  If you
	type part of a dataref name into the dataref combo-box, you can search
	among all datarefs for matches.
	
You can click the "go" button next to the value 0 and value 1 fields to change
the current preview of your model to this time.

The "add" and "delete" buttons can be used to add keyframes.  Objects start 
with two key frames, animating linearly between them.  By adding more key
frames you can create more complex relationships between the dataref value and
the animations.

Use the "Animation time..." command to show the animation time controller 
window.  This window has the following options:

Show Animation

	Check this to enable animation previews.

For each dataref

	The slider will move the previewed value of the dataref, animating
	your model.
	
	The "select" button will add any animation command lines that use
	this dataref to the current selection.

Resync

	Sometimes the current list of datarefs won't match your model - click
	resync to update this window.
	
WARNING: the animation preview will affect where you see your model but
will NOT affect AC3D editing.  You should turn off animation preview when 
editing to assure that AC3D's user interface works correctly.

-------------------------------------------------------------------------------
MANIPULATORS
-------------------------------------------------------------------------------

You can read about the concept of manipulators here:

http://wiki.x-plane.com/Manipulators

With the ac3d X-Plane plugin, the manipulation is a property of each object
you create.  Simply pick the manipulation type in X-Plane inspector window.
Additional fields will appear to let you customize the manipulation, when
appropriate.

Important: in ac3d, panel clicking and panel texture are not the same - you
must specifically set the panel manipulation on any panel texture that you want
to be clickable!  This is new to version 3.2 of the plugin - you will have to
update your .ac objects.

-------------------------------------------------------------------------------
UPDATING OLD .AC FILES
-------------------------------------------------------------------------------

If you have an AC3D .ac file with animations from the old 2.0-style plugin you
must update your model in order to see datarefs and have the special X-Plane
attributes be exported.  Simply pick "Update from old plugin" once to update.

-------------------------------------------------------------------------------
PERFORMANCE
-------------------------------------------------------------------------------

Performance of your OBJ model dependes on the number of times that you change
state, whether that be due to animation, attributes, etc.  X-Plane does not
change the order of the object, and AC3D exports the object in order of the
hiearchy window.  It is therefore important that you organize your hierarchy to
minimize the number of state changes.

You will get a state change whenever the following things change:

- Polygon hardness, polygon offset, blending on/off.
- One vs two sided geometry, smooth shading.
- Panel vs normal texture.
- Any animation command (both the beginning and ending.

So it is best to group these things together.  Please note that you will not
get a state change if a property doesn't change; having two objects in a row
with the names

_POLY_OS=1
_POLY_OS=1

will not cause a change between them because the _POLY_OS has been specified
in both, but does not change from the first to the second.

Be careful with 1/2 sided geometry and smooth shading - since these are set per
surface, it is possible to have a huge number of changes of these without
noticing!  Your best bet: set all of your objects at once to have the mode
you want.

Also if you use smooth shading but an object does not look smooth due to crease
angle, it will look exactly the same in AC3D and X-Plane.  Therefore your best
bet is to ALWAYS use smooth shading and use the crease-angle function in AC3D
to decide what looks round and what looks like it has flat sides.

Changing to the panel texture is the most expensive state chagne, so be sure
to group all of your panel textured objects together!

One good way to see how much state change you have is to look at your OBJ file
in TextEdit or WordPad after exporting it.  Skip to the end; each "TRIS"
command means that state was changed and drawing restarted.  Ideally you will
have only one TRIS command for the whole file, or at least as few as possible.

-------------------------------------------------------------------------------
CALCULATE X-PLANE LOD COMMAND
-------------------------------------------------------------------------------

This command attempts to calculate the farthest level of detail distance that
is appropriate for your object, based on it its approximate size.  Select the
entire object and select "Calculate X-Plane LOD" from the tools menu.  A 
message box will suggest an LOD such as "Recommended LOD Distance: 1134 
meters."   This is just a recommendation; you may want to increase or decrease
this  distance for your preferences.

To actually apply the level of detail, create a a new LOD group using the 
X-Plane menu and use the X-Plane Properties dialog box to edit the LOD 
distances.

-------------------------------------------------------------------------------
CALCULATING BATCHES
-------------------------------------------------------------------------------

A batch is a set of triangles or lines that all have the same properties, and
thus can be drawn by the GPU without CPU intervention.  Generally speaking,
more batches means lower framerate - the number of batches of triangles
X-Plane can submit to the graphics card is a limiting factor on fps.

The ac3d plugin can estimate the number of batches for a selected set of 
objects.  Simply select some or all of your model and pick "Calculate Batches
For Selection." 

This prediction has some limitations:

- It does not count batches caused by changes between 1-sided and two-sided
  geometry, or flat-smooth shading.  To avoid extra batches, set your entire
  workspace to 1-sided or 2-sided (if 1-sided, you can duplicate and flip
  triangles to make two-sided geometry).  Keep all objects smooth-shaded and
  use crease-angles to control the smoothnes of objects.
- It does not count batches caused by changes from lines to triangles.
- It doe not cause batches caused by animation.
- If you select multiple LODs, it will count them all as if they would all be
  drawn at once.
- If you select objects that are not adjacent in the hierarchy, the estimate
  will not take into account the (possibly quite negative) effect of 
  unselected surfaces.
  
Generally the most accurate way to count batches is to export your object and
count TRIS and LINES statements.  But this command can give you a quick
indication of problems; often copying and pasting can result in very 
inefficient ordering of objects and state changes.

The ac3d OBJ exporter will try to optimize state change when it saves your
model (and x-plane will further optimize state change if possible) but neither
the exporter nor X-Plane will change the draw order of your object, which
comes from the hierarchy.  Thus a hierarchy order that changes state a lot will
directly lead to low framerate.

You can use the "Optimize Selection" command to reorganize the selected objects
to minimize the number of batches.  The optimize selection command will only
reorder objects if the number of batches can be reduced.  Objects will be 
shifted the minimum amount to optimize.  However, a number of serious warnings:

- The heuristic for optimization is based on the batch count above, so every
  one of the confounding factors that (animation, unselected objects) can
  lead to false optimizations, or a refusal to optimize.
- Objects are moved into the most specific group that contains the entire
  selection; this can ruin a carefully organized large project.
- The optimization command doesn't understand animation - usually it will
  pull geometry out of aniation groups, effectively ruining animation.

The optimzier will not change unselected geometry, allowing you to optimize
parts of your geometry.

I recommend using the optimizer as follows:

1. First, organize your object into major groups, based on animated vs.
   static geomertry.  Keep translucent geometry (that must be at the end)
   and polygon offset geometry (that must be at the beginning) separate.
   
2. Then select each homogenous sub-group and use the optimizer to minimize
   changes in blending control.

-------------------------------------------------------------------------------
CHANGE TEXTURE COMMAND
-------------------------------------------------------------------------------
You can use the change texture command to change the texture of your object
without disturbing the texturing of each polygon.  In order to do this, the
new texture (the _replacing_ texture) must fully contain the image of the
object's current texture (the _replaced_ texture).  This image of the current
texture cannot be squished, stretched, color adjusted, or rotated in the new
texture.  However, the space in the new image around the old texture can 
contain anything.  The new and old textures must both have (or not have) alpha.

Select the object(s) you want to do the texture replace on and select the
"Change Texture..." command from the tools menu, and pick a .BMP or .PNG file
that will be the new texture.  For every selected object whose texture is
contained in the new texture, two things will happen:

1. That object will now use the new texture as its texture.
2. The texture coordinates of every surface in that object will be adjusted so
that the object's appearance does not change, even though the layout of the
new object is different.

Two example uses of this command:

1. You have a house object with a 256x256 texture, and you want to add some
trees, but you do not have room in the texture to add the tree bitmaps.  You
create a new 512x256 bitmap, with the old 256x256 bitmap on the left side.
Select your house and pick Change Texture and select the new 512x256 bitamp.
All texture coordinates are modified so that the house uses the new bitmap.
You now have the whole right side of the 256x256 bitmap to use for tree 
bitmaps.

2. You have a house object with a 256x256 bitmap, and a car object with a
different 256x256 bitmap.  You want to combine them into a house with a car
parked as one object, but they use different bitmap files.  You create a new
bitmap in photoshop with the house on top, the car on the bottom, that is 256
x512 pixels tall.  You then import both the car and house into AC3D and 
position them where you want.  You select all of these objects and do a
Change Texture to the new 256x512 combined bitmap, and now the house and car
use one big bitmap.  You can then export this new house adn car scene as a
single object with a single bitmap and use it in x-plane.

(This second technique is powerful when you are working with a lot of detail
in an urban setting and you want to reduce the object count to increase 
framerate.)

-------------------------------------------------------------------------------
REMAP TEXTURE COORDINATES
-------------------------------------------------------------------------------

This opens up the texture coordinate remapper.  By entering texture ST 
coordinates in this window you can change the textures of an object.

For example, if your texture is 512x128 but you decide to expand it to 512x256
(putting the old texture in the top half of the new one) to make more space
for yourself, you would use these remap values:

Old Left:	0		New Left:	0
Old Bottom:	0		New Bottom:	0.5
Old Right:	1		New Right:	1
Old Top:	1		New Top:	1

Use "remap selected" to change the current selection.

Use "remap directory" to change an entire directory of .ac files.

WARNING: remapping a directory will delete the current model as the entire
directory is opened, converted, saved, and closed!

-------------------------------------------------------------------------------
MAKE TRANSPARENT COMMAND
-------------------------------------------------------------------------------

This command changes the magenta color of a .bmp-based texture into
transparent pixels to simulate what you would see in x-plane.  Select the
object and pick "Make Transparent" from the tools menu.  All textures used
in the selected objects are changed.  This command may only be used on
RGB textures without alpha.  Like X-Plane, this command only converts perfect
matching #FF00FF magenta.

-------------------------------------------------------------------------------
MAKE NIGHT LIGHTING COMMAND
-------------------------------------------------------------------------------

This command attempts to merge the texture of an object with its night 
lighting counterpart to show you what it would look like lit.  Select
an object and pick "Show Night Lighting" from the tools menu.  All textures
used in the selected objects are changed to look like night lighting.

You can use the 'reload texture' command from AC3D's texture menu (under
the object menu) to reload the normal daytime texture.

-------------------------------------------------------------------------------
MAKE TREES COMMAND
-------------------------------------------------------------------------------

The make trees command provides a quick way to make "3-d trees" from quads.
For each quad selected, the make-trees command makes four one-sided copies 
rotated 90 degrees each around the middle of the quad to form a + shape.  The 
whole configuration is then rotated a random amount.  The quads are marked as 
1-sided.

NOTE: the reason that four one-sided quads are used (rather than two two-sided)
quads is two-fold:

- This allows the whole object to be one-sided, avoiding the use of ATTRibutes.
  See the one-sided command for more info on the advantage of smooth shading.
- When the geometry is two-sided, one half of the tree texture will be visible
  on both sides of the tree.  With two one-sided quads, less repetition is
  visible.

The normal vectors of the trees are pointed straight up.  See the up-normals
command for more informatino on the advantage of up-facing normals.

The quads are set to smooth shading.  Generally you should set the entire
object's shading to be smooth.

-------------------------------------------------------------------------------
MAKE ONE-SIDED COMMAND
-------------------------------------------------------------------------------

There is an advantage to keeping an entire object one-sided or two-sided; one-
sided geometry offers more flexibility, more realistic lighting, and faster
performance assuming that not too many polygons need to be duplicated.

The "make one-sided" command copies every selected two-sided surface and 
reverses its vertex order to form a one-sided surface.

-------------------------------------------------------------------------------
MAKE UP NORMALS COMMAND
-------------------------------------------------------------------------------

A "normal" vector is an arrow attached to each vertex or surface of your model
that tells X-Plane how the sun lights up your object.  Usually the normals
point directly away from your surfaces, causing realistic lighting.  (For
example, if you create a building, the sides will be brighter at sunrise and
sunset, while the top will be brighter during the day.)

If the normals are changed other lighting effects can be achieved.  In
particular, a normal that points straight up will cause a variation of 
brigthness based on the overall time of day, with the brightest times at noon.

One problem with typical 3-d trees (formed by the crossing of two vertical
rectangles) is that at sunset one of the quads will be very brightly lit
(because it is facing the sun) and the other will be quite dark (because it is
not).  The result is a mismatch in the color of the tree quads (light vs dark
green) and a strange looking tree.

By setting the normals of the entire tree to point straight up, the entire tree
picks up a general brightness from the time of day, but does not have 
incongruent lighting.

-------------------------------------------------------------------------------
CONVERT DIRECTORY TO OBJ8
-------------------------------------------------------------------------------

You can convert an entire directory of .ac files to OBJ8 files.  Pick this 
command and select a directory.  The plugin will open every .ac file and
save it as an OBJ file with the same name in the same directory.

WARNING: this command will trash whatever model you have open!

-------------------------------------------------------------------------------
BULK EXPORT
-------------------------------------------------------------------------------

This command will export every "top level" object (object in the top of the 
hierarchy) as an OBJ.  The object's name is used as a file name.

If you have a complex model like an airport that is exported as multiple OBJs,
use this to export the whole thing quickly.

-------------------------------------------------------------------------------
BY-TEXTURE EXPORT
-------------------------------------------------------------------------------

This command exports one or more objects based on the textures used, allowing
the entire workspace to be exported with a minimal number of objects.  
Geometry that has no texture or does not require a texture (lines, lights, 
panel-textured objects) are exported to the first object that is emitted.

-------------------------------------------------------------------------------
RELOAD TEXTURES
-------------------------------------------------------------------------------

The reload textures command will reload all PNG files, showing any changes that
have been made on disk.

-------------------------------------------------------------------------------
X-PLANE EXPORT SETTINGS
-------------------------------------------------------------------------------

A few settings can be customized for the plugin:

Default layer group (and offset)

	Normally a layer group must be specified per object.  But if you
	set this preference, any objects that don't have layer groups will
	be exported using this layer group (and offset) instead.  
	
	See the OBJ8 spec (ATTR_layer_group) for more info on layer groups.
	
	This feature can be used to export a whole series of objects all 
	with a special layer group.

Export Geometry

	If this is unchecked, no polygons will be exported from your object.
	This defaults to on, and 99.9% of the time you should leave it on!

Default LOD

	Normally if you don't specify LOD in an object, no LOD is placed in that
	object.  By putting a number other than zero here, the plugin will export
	an LOD range of 0..N for any unlabeled objects.
	
	(If you have a large number of objects that all nee artificial LOD
	restrictions this can help!)

Bulk Export Prefix

	This string will be prefixed to the name of any file that is exported,
	from the bulk conversion, bulk export, or file->export menu items.
	
	You can use a partial file path to export into a directory.  For example
	preview/ is a valid prefix that would cause everything to be saved in
	a subdirectory called preview.
	
Texture Export Prefix

	This stirng is prefixed to the names of any textures that are output.

-------------------------------------------------------------------------------
WARNING MESSAGES
-------------------------------------------------------------------------------

The AC3D may spit out some warning messages when you export an object:

"Warning: 3 objects did not have textures assigned.  You must assign a 
texture to every object for X-Plane output."

	This warning happens when one or more polgon surface is missing a texture.
	X-Plane draws all polygons with textures, so if you don't assign a texture
	and adjust that surface's texture coordinates, you will probably see 
	random junk in x-plane.  Select all objects and pick a texture from the
	Object -> Texture menu to fix this.

"This model uses more than one texture.  You may only use one texture for an 
X-Plane OBJ."

	Not counting a special panel texture for cockpit objects, you can only use
	one texture per X-Plane object.  Pick one texture and assign it to all non-
	panel surfaces to pick this.
	
	WARNING: if you have a texture assigned to line geometry, it must be the
	same textures as polygons have, even though this texture is ignored.

"This model has non-quad surfaces that use the panel texture.  Only quad 
surfaces may use the panel texture in OBJ7."

"This model has non-quad surfaces that are marked as hard.  Only quad surfaces
may be hard in OBJ7."
    
	Hard polygons and panel-textured polygons are only available for quads in
	OBJ7.  In OBJ8 this is not an issue.  One note: this warning message will
	come up any time you may possibly have triangles without these properties.
	However since the AC3D exporter does its best to combine triangles into 
	quads when exporting to OBJ7 and they are hard or panels, you may find that
	while you got this warning, the actual OBJ is partly or fully okay.  It is
	always safest to use quads though if you need to export to OBJ7.

With all of these warnings, AC3D will try to select any offending surfaces or
obojects to help you locate the problem.  AC3D may not be able to select all
of the problem areas at once; so it may take repeated exports to diagnose all
problems.  Also, you may need to put AC3D into Surface or Object selection
mode to get a better selection for diagnostic purposes.

