Usage Notes
(stuff that will eventually go into a To Do list or elsewhere)
Because of certain considerations, Vision does not follow the Cocoa convention of reference counting in most situations and thus you should expect that most of the objects that you deal with will always have a reference count of 1. When releasing Construct objects, almost all other objects having anything to do with it as well as all of it's child Constructs will also be released.
Because Vision's input abstraction model is very flexible and is made to be able to interface with multiple input devices (like multiple mice for instance) and multiple input abstractions (multiple cursors for example) it gets its input events directly from the devices and for the most part is operating system event agnostic. Thus mouse clicks and movements will still be delivered to the Vision server even if its window is not behind other windows or is not even visible at all. There are future plans to make it so that when Vision is running alongside another operating system window server as it is currently implemented, it will do better at behaving nice event-wise.
The template projects
and targets that Vision supplies for XCode have
settings that suppress errors for undefined symbols. This is
because dynamic libraries of type "bundle" cannot dynamically
link currently and thus their undefined symbol resolution can not be
fulfilled. Code dependencies are taken care of by LoadObject()
and UnLoadObject() calls in constructor/destructor functions of server
modules. Thus you will need to make sure that
all
of the symbols that you need to link to will be resolvable at runtime
through those mechanisms because the linker will no longer do it for
you (until a solution is
found).
There is currently a
bug in the Objective-C runtime used in Darwin/OS X (objc4-267) which
will
cause a crash in certain situations of module re-loading. Apple
is aware
of the problem but as of 10.4.5 it has not yet been addressed.
For those who wish (do so at your own risk) you can compile your own
version of the Objective-C
runtime with one line changed which will fix
the problem.
For objc4-267 Change line 1984 in the file objc-runtime.m from:
cls_refs_end = (struct objc_class **)(size + (uintptr_t)cls_refs); to:
cls_refs_end = (struct objc_class **)(size * sizeof(Class) +
(uintptr_t)cls_refs);
Although Vision has
been built as a universal binary it has never been
tested on an x86 machine and in all likelihood will not run correctly
in the state that it is in currently. As soon as the right
hardware can be obtained for testing it will probably not take very
long to get it up and running though.
Right now there is a mix of using both NSStrings and plain old C strings for various functions and capabilities. Eventually using NSStrings for everything will probably become standard with a few exceptions.
The core server operations were designed to be operated as a single thread and although in the Application Library paradigm you may make a program that spawns multiple threads you must remember to not invoke any code that is thread context sensitive (such as OpenGL code) from another thread and also be aware of potential synchronization problems. For synchronization in the Application Library paradigm there is a NSRecursiveLock supplied called ThreadLock that locks the main server/program thread down during any time that Construct objects or most anything else having to do with Vision is accessed.
Although there are future plans to track, manage and segregate OpenGL state, for right now everybody plays in the same sandbox.
DRAWREAL and DRAWVIRTUAL enums tell the Construct object what mode to draw in. DRAWREAL means that we are actually need to draw the full quality version of the object for purposes of displaying on the screen. DRAWVIRTUAL tells the object that it only needs to draw a reduced quality version for purposes of creating similar OpenGL fragments for things like picking which are crucial to Abstraction interaction.
Every once in a while
you might see compiler defines that are meant to
filter out scope from certain kinds of targets. For the most part
you
will not have to worry about them except for server module authors who
should filter out certain parts of their interfaces in the header files
for projects built with the window
server
paradigm.
Some of these you will probably never see in use, but are included here
for
completeness.
VISIONMODULE - Anything
that should have access to modules.
Pretty
much everything except for client apps built under the window server
paradigm.
VISIONAPP - To be used only for compiled Vision applications.
VISIONSERVER - To be used only by the Vision server regardless of how
it is packaged (application library or window server).
VISIONDAEMON - To be used only by the Vision window server.
VISIONLIBRARY - To be used only by Vision when packaged as a library.
Compatibility between module versions is an issue that has not yet been fully addressed and so thus in it's current implementation it is best to copy the modules that your application makes use of into the Resources directory of your app bundle. By default the Vision Application library (libVision.dylib) looks there for modules at runtime anyway and this will allow you to make Applications that are completely standalone.