Developer Documentation

From K-3D

General

• Getting Started - Platform-specific instructions on how to build or install K-3D.
• New in K-3D 0.7! Browse Subversion - You can inspect the K-3D sources and their history online.
• rsync Mirror - You can mirror the K-3D CVS repository (including complete history) using rsync.
• Source Documentation - Docs automatically generated from the K-3D sources.
• K-3D Dashboard - K-3D includes automated regression testing, see the latest results in the Dashboard.
• SourceForge Project Page - K-3D's source repositories, bug and patch trackers, and downloadable files are graciously hosted by the SourceForge project.
• Professional Development - Reserved for professional publications by K-3D contributors.
• Developer Bibliography - Further reading for developers.
• Logos - Logos and other project graphics.
• Developer Nicknames - Official, and incredibly scalar-important!
• Future Work - A central location for forward-looking ideas, design documents, and general speculation.
• Developer Meetings - Our attempt at holding regular organizational and technical meetings.

Debugging

• Debugging - Brief overview on how to debug crashes
• Debugging Exceptions

Design

Build

• Visibility - Experiments with the GCC symbol visibility mechanisms.

Data

• New in K-3D 0.7! Binary Resources - Details on how you can embed files in K-3D binaries for use at runtime.
• Bitmap Storage - Explains how bitmap data is handled internally in K-3D.
• Data Containers - Describes K-3D's policy-based design for storing plugin data.
• File IO - For all your input and output needs.
• New in K-3D 0.7! Filetype Detection - Covers the mechanisms K-3D uses to identify filetypes and match them to plugins (for import/export, scripting, etc).
• New in K-3D 0.7! Fundamental Types - K-3D defines a set of fundamental (integer, float, string) types that should be used for all new code.
• Rotation Data - Describes objects for storing 3D orientation data.
• XML Parsing - Describes the toolkit used for working with XML data.

Documentation

• Recording Tutorials - Guidelines and documentation on how to record new interactive tutorials.

Meshes

• New in K-3D 0.7! Array Based Mesh Design - Discusses the array-based mesh data structure.
• New in K-3D 0.7! Mesh Painters - Discusses the new framework for rendering mesh data in OpenGL.
• New in K-3D 0.7! Painter Types - An overview of how painters can handle face normals, edges, per-vertex colors, and other specialized drawing styles.
• New in K-3D 0.7! Mesh Painter Gallery - A gallery of mesh painter styles, many written in Python!
• New in K-3D 0.7! GTS Plugins Removed - In case you were wondering ...
• New in K-3D 0.7! CGAL Boolean Operations - Work-in-progress page on the new boolean implementation using CGAL
• Implicit Surfaces - K-3D includes support for implicit surfaces (RenderMan blobbies).

Plugins

• Plugin Design - An overview of how K-3D plugins work.
• Plugin Classes - Covers the important distinction between application and document plugins.
• Plugin Licensing - Important information regarding plugin licensing.
• New in K-3D 0.7! Plugin Metadata - Describes how plugin authors can provide arbitrary metadata to describe their plugins.
• New in K-3D 0.7! Node Metadata - Information on how arbitrary metadata can be associated with individual document nodes.
• New in K-3D 0.7! Building Plugins - Covers different options for building K-3D plugins.
• New in K-3D 0.7! Plugin Tutorial - A "hands-on" guide to creating your own plugins.
• On Demand Modules - Discusses how K-3D delays loading plugin modules until they're needed.
• New in K-3D 0.7! Virtual Plugins - A new mechanism allows concrete plugin instances to be created by "virtual" factories.

Properties

• New in K-3D 0.7! Property Metadata - Describes how arbitrary metadata can be associated with properties to provide a better user interface.

Rendering

• Cameras And Render Engines - Discusses how cameras, render engines, and other objects interact in K-3D.
• Layered Shaders - Highly experimental Aqsis specific feature.
• Material Design - Details how materials are assigned to geometric primitives.
• Negative Scale - Information on how to handle OpenGL normals properly when a transformation matrix has negative scale factors.
• RedrawAll - A few words on how the display gets updated.
• Render Models - Discusses how render engines, lights, and materials interact in K-3D.
• RenderMan API - Describes K-3D API that handles RenderMan output.
• Shader Paths - Discusses the rationale for referencing shaders by filesystem path instead of name.

Scripting

• Script Engines - Details on creating plugins to support new scripting languages.
• Scripting - Provides an introduction to K-3D scripting.
• Python - Documentation for the Python script engine used for most general-purpose scripting tasks.
• RenderManScript - Injects arbitrary RenderMan API calls into the rendered scene.

Selection

• Selection Design - Explains how selection is handled internally.
• Selection Use Cases - Selection use cases that drove the current design.

Subdivision Surfaces

• SDS Preview - Ongoing work on adding realtime SDS preview to the K-3D UI.
• SDS Corners - Info about variable sharpness corners on SDS models.
• SDS design doc - Short explanation on the design of the SDS preview

Testing

• Comparing Floating-Point Numbers - How to compare floating-point numbers across different platforms.
• New in K-3D 0.7! Running Regression Tests - How to use the K-3D regression test suite.
• New in K-3D 0.7! Writing Regression Tests - All new code must include regression tests!

Time

• Time Design - Provides an overview of how "time" works within a K-3D document.

User Interface

• Next Generation User Interface - The central location for discussion on the 0.6 UI.
• Shutdown Warnings - Discussion on how to prevent accidental loss of data during normal shutdown.
• Snap Design - Covers the new framework for interactive "snap" behavior.
• Tool Design - Discusses the relationships among nodes, tools, and the user interface.
• Widget Toolkit - Describes the toolkit used for the standard user interface.

Visualization Pipeline

• Visualization Pipeline - K-3D uses a sophisticated graph-based visualization pipeline to implement procedural modeling and animation.
• Visualization Pipeline Display - Some initial thoughts on a pipeline visualization component.
• Pipeline Hints - Describes how upstream nodes in the pipeline can send "hints" to downstream nodes when changes occur.

Administrivia

• Coding Guidelines - Fashionable K-3D code must meet these guidelines.
• Copyrights And Licensing - Enumerates K-3D's licenses and copyrights.
• CVS - A brief introduction to CVS.
• Foo - what does it mean, what is it good for?
• GNOME Human Interface Guidelines - These are required reading for K-3D UI developers.
• Internal Libraries - Describes K-3D's internal library design.
• Internationalization - Covers technical details of how to write code that can be localized (translated into other languages).
• Localization - Discusses how to create and maintain locales (language translations).
• Logging - K-3D provides a standard framework for logging and debugging messages.
• Naming Conventions - Doh! Had to happen!
• One Definition Rule - know it, live it, love it!
• Portability Guidelines - Provides some hard-won wisdom on writing portable K-3D code.
• New in K-3D 0.7! Release Checklist - Covers how official releases are created.
• Submitting A Patch - It's easy, and you'll be the envy of all your friends.
• Tabs And Indentation - You knew this had to be coming, right?
• Testing And Debugging - Help with testing and debugging problems in K-3D.
• Version Numbers - There is method to our madness.

Legacy Documentation

The following documents cover obsolete / deprecated documentation for historical reference:

• K-3D 0.6 Only! AutoTools - The Thou Shalts and Thou Shalt Nots of our GNU Autotools build system.
• K-3D 0.6 Only! Browse CVS - You can inspect the K-3D sources and their history online.
• K-3D 0.6 Only! Iterating Edge Loops - The right (and wrong) ways to iterate over legacy edge loops.
• K-3D 0.6 Only! Legacy Mesh Data - Discusses k3d::mesh and related geometric data structures.
• K-3D 0.6 Only! Legacy Mesh Modifier - Explains what a mesh modifier is in terms of the K-3D API.
• K-3D 0.6 Only! Legacy Parameter Storage - Describes storage of geometric normals, per-vertex color, and other custom parameters.
• K-3D 0.6 Only! Legacy MeshInstance Cache - How the MeshInstance plugin caches geometry for efficient Viewport rendering.
• K-3D 0.6 Only! Legacy Branch Checklist - Details the process for creating an official branch in the source tree.
• K-3D 0.6 Only! Legacy Release Checklist - Covers how official releases are created.
• K-3D 0.6 Only! Legacy Mesh Source Plugin Tutorial - A more specific tutorial on creating a plugin that uses K-3D's pre-0.7 mesh API.
• K-3D 0.6 Only! Legacy Plugin Tutorial - A slightly-out-of-date tutorial on creating plugins.