Go to Google Code Home
Google SketchUp SkpReader C++ API Documentation (Labs)

SkpReader API Documentation

8.0

Overview

The SkpReader C++ API provides read only access to the information in a SketchUp model. The API is available via two mechanisms: the SketchUp application itself, and a standalone SkpReader binary (sketchupreader.dll or SketchUpReader.framework).

Typical application that are built with the SkpReader API include:

Examples

This SDK package contains several examples to help you avoid common pitfalls when using the SkpReader API. The examples tab provides some short snippets of code to accomplish common tasks. The SkpToXML exporter example in the Examples folder is a fully developed SketchUp plugin exporter which can be compiled and used in SketchUp. The xml format it outputs is arbitrary and only meant show a human readable form of the model data extracted from the .skp file.

How to invoke the API objects

There are two techniques for getting access to the SkpReader API objects: write a SketchUp plugin exporter or use the SkpReader binary in a standalone application.

The API available through the SketchUp Application.

A SketchUp plugin exporter is a piece of code that is dynamically loaded at runtime when a user indicates that they wish to export the model, view, section slice or image.

On the Windows platform an exporter is implemented by creating a COM DLL which contains a class that implements IEnumSketchUpExporter interface. See the SkpToXML Exporter example in the Examples folder for the details on how to do this.

The SkpReader C++ API is only valid for the life of the method call that invoked the ISkpApplication's creation. That is, if someone is writing a SketchUp plugin exporter, they must not hold onto the interface pointers beyond the life of the export call. In short, the API objects are not guaranteed to be valid if the model changes.

The API available through the SkpReader binary

The SkpReader C++ API comes with a SkpReader binary (a shared library on the Mac, a COM server DLL on Windows) which can be used to write custom applications that read from a SketchUp file (a .skp file).

Since there is no SketchUp application running when the SketchUp Reader is invoked, some of the interfaces available in the full API are not supported. In particular, the ISkpHLRGeneration and ISkpViewProvider interfaces are not supported by the SkpDocument and SkpApplication coclasses, respectively.

Users reading SketchUp files using the SkpReader binary cannot change the underlying model, but aren't as restricted in how long interface pointers can be referenced, as there is no possibility that the model may change.

Naming Convensions

Interface Names

The SkpReader API interfaces are all prefixed with ISkp.

Method Names

It is important to note that this documentation is generated from the IDL file describing the SketchUp API. Therefore, the distinction between getter and setter ('get_' and 'set_') methods may be somewhat obscured. That is, for a particular method F of the 'propput' variety, the generated C++ code will include the function put_F, similarly for the 'propget' variety, the C++ code will include the function get_F. In this documentation, however, the prefixes are not included, as there are cases (e.g., VB, COM-smart pointers etc.) where the prefixes are not added. Thus, it is incumbent upon the user to note the special method documentation [propget] and [propput].

For example, if a method is described as

HRESULT  Y ([out, retval] doublepVal) 
        [propget] Get the y-value of the point. 

then the generated C++ code would include a function

HRESULT get_Y(double* pVal); 

Similarly for propput methods.

In the ISkp interfaces, there are two types of point and vector 'getter' methods.

The first is designed for efficiency, but is only applicable for in-process applications. These are methods that act like propget methods, but are not. They are prefixed with _Get.

The second type of getter methods are the traditional propget methods. These do not appear with the prefix get_ in this documentation, but C++ clients using the raw interfaces will need to prefix the method names with get_.


©2010 Google - Google Home - About Google