Executive summary for people who don’t like rambling anecdotes: property lists and user defaults should always be type-checked, and this makes it easy.

Oolite is highly moddable, with over 150 expansion packs. Most of them are interoperable, and typically many will be in use at once. Essentially all of these contain property lists, generally written by hand by non-programmers, often on systems without plutil or Property List Editor. As such, many contain parse errors or structural problems.

Previous versions of Oolite blithely ignored the imperfections of mere humans. Unparseable property lists were effectively ignored, leading to unexpected behaviour, often quite subtle. Structural errors, however, caused exceptions, most of them seemingly at random.

The current test releases address the syntax issues by dumping the error string from NSPropertyListSerialization and the path to the relevant file to the game’s run log. A certain amount of context-sensitive type checking is done in certain areas, such as scripting (yes, property lists are used for scripting, although that’ll be deprecated in the next stable release).

The most significant fix, however, has been to replace most uses of -objectForKey: and -objectAtIndex: with methods that check types and perform conversions where they make sense. In particular, strings are automatically converted to numbers and booleans where appropriate, which is needed to work with the more pleasant OpenStep plist syntax. When a plist value can’t be converted to the required type, or simply isn’t there, an appropriate default value is used. The game will no longer try to get keyed objects from an array, or find the first character of a dictionary. Instead of code like this:

// Hope plist has correct structure.
unsigned myMagicNumber = [[[plist objectForKey:@"someArray"] objectAtIndex:3] unsignedIntValue];

or more fault-tolerant code like this:

unsigned myMagicNumber = 0;
id array = [plist objectForKey:@"someArray"];
if ([array isKindOfClass:[NSArray class]] && [array count] > 3)
{
    id number = [array objectAtIndex:3];
    if ([number respondsToSelector:@selector(unsignedIntValue)])
    {
        myMagicNumber = [number unsignedIntValue];
    }
}

we now have code like this:

unsigned myMagicNumber = [[plist arrayForKey:@"someArray"] unsignedIntAtIndex:3];

which will not throw an exception if @"someArray" is not an array or if the array has less than four members, but will instead return 0. It’s also shorter than the broken version. Default values other than 0 can be provided in the form [array integerAtIndex:3 defaultValue:-1] or [dictionary unsignedShortForKey:@"value" defaultValue:14].

Oolite is obviously an extreme case, but many applications deal with property lists. Even more deal with NSUserDefaults, which of course is a wrapper around property lists. You may think that you know what you’re putting into user defaults and can therefore rely on it to be correctly structured, but if you’re thinking that you’re wrong. First, users will modify your preferences file, break it, and forget they did it. Second, your code is buggy. If you write any sort of collection to your prefs, there’s a chance that you’ll put an object of the wrong class there if the phase of the moon is unusual. If you don’t check it when you read it, this will cause an exception, and you’ll end up guiding a user through digging around in ~/Library to clean up your mess. Better to be fault-tolerant to start with.

So, here it is: JAPropertyListAccessors 1.0.2 (MIT/X11 license). It provides:

• A non-throwing variant of -[NSArray objectAtIndex:].
• Functions to convert objects (NSNumber or NSString) to all standard integer types, as well as float and double, clamping the results rather than overflowing, and returning a user-specified default value if no conversion can be performed.
• Convenience methods for accessing integers, floats, strings, arrays, dictionaries, sets, or objects of a specified class from NSArray, NSDictionary or NSUserDefaults. The following transparent conversions are performed when appropriate: NSString to numbers; NSNumber and NSDate to NSString; NSArray to NSSet.
• Convenience methods to set integers and floating-point values in NSMutableArray, NSMutableDictionary and NSUserDefaults.
• Unit tests for the primitive conversion functions.
• Compatible with 32-bit and 64-bit runtimes, and with garbage-collected and non-GC code.
• Very little in the way of comments.

Update (version 1.0.1): Default value (rather than nil) is now returned when conversion to string fails. String conversion now uses -stringValue if available.

]]> http://jens.ayton.se/blag/property-list-extractors/feed/ 1 http://jens.ayton.se/blag/priority-queue/ http://jens.ayton.se/blag/priority-queue/#comments Fri, 14 Sep 2007 16:01:10 +0000 Jens Ayton http://jens.ayton.se/blag/priority-queue/ Continue reading →]]> The Foundation framework: it has some collections. It doesn’t have others.

In particular, it doesn’t have a priority queue, which I need. CoreFoundation does, but this is for Oolite so it needs to work with GNUstep. Yes, I could bring in all of CFLite, but without the toll-free-bridging it’s not particularly attractive.

Mike Ash (who seems to be getting an indecent amount of exposure in this blog, to the extent that it counts as an exposed location) wrote about the issue last year. His solution was to use the C++ Standard Template Library, but I don’t like that solution much because a) GNUstep doesn’t play nice with Objective-C++ (its headers aren’t C++-clean) and b) it’s C++.

So, as you may have guessed, I’ve gone and written one. Here it is, with the small amount of Oolite dependency ripped out. MIT/X11 license.

Operations supported:

• Add object.
• Add all objects in a collection (anything that responds to -objectEnumerator or -nextObject).
• Retrieve highest-priority object. Priority is defined by a comparison method specified when creating the priority queue. Priority is defined such that the NSOrderedDescendingmost object has the highest priority; as such, using caseInsensitiveCompare: as the comparator will cause strings to be retrieved in lexicographic order.
• Delete highest-priority object.
• Delete specific object.
• Delete equal object (i.e., delete one object such that the comparator returns NSOrderedSame).
• Retrieve all objects in sorted order, emptying the queue.
• Equality testing and (low-quality) hashing.
• Copying of the entire queue.
]]> http://jens.ayton.se/blag/priority-queue/feed/ 5 http://jens.ayton.se/blag/glsl-uniform-bindings-for-cocoa/ http://jens.ayton.se/blag/glsl-uniform-bindings-for-cocoa/#comments Mon, 30 Jul 2007 22:24:01 +0000 Jens Ayton http://jens.ayton.se/blag/glsl-uniform-bindings-for-cocoa/ Continue reading →]]> Executive summary: This article demonstrates the use of Objective-C’s dynamic object model and the Foundation framework to extract attributes from objects using information not available at compile time. This is done on the context of implementing OpenGL Shader Language support in a cross-platform game.

Introduction

A major feature of the current development line of Oolite is support for GLSL shaders. Shaders need to be able to reflect the state of the object they’re attached to – for instance, by having spaceship engines glow in proportion to engine power. The mechanism GLSL provides for this is uniform variables, attributes set by the host application and read by the shader.



Debris model with per-pixel lighting and heat glow which fades over time from glow_alloy.oxp. Model by Arexack_Heretic, textures by Griff, shaders by Ahruman.

The initial implementation of shader support was quite simplistic:

for (each material in model)
{
    if (material is shader-based)
    {
        glUseProgramObjectARB(shader);
        if (shader uses uniform:"time")
        {
            glUniform1fARB(location for "time", current game time);
        }
        if (shader uses uniform:"engine_level")
        {
            glUniform1fARB(location for "engine_level", ship’s engine power level);
        }
        …
    }
    else
    {
        glUseProgramObjectARB(NULL);
        set up texture;
    }
    render geometry for this material;
}

The problem

This gets the job done, but it isn’t exactly a paragon of object-oriented design. There’s no encapsulation and no reuse. It’s definitely not very Cocoa-ey. The first step was obviously to make materials into a class hierarchy, with simple texture-based materials being one class, shader materials being another and the rendering code not really caring which was being used. However, if the shader material class set uniforms in the way outlined above, it would require the shader material class to know about the details of the various types of entity in the game, and special-case each one. Conversely, if the responsibility for setting up uniforms remained in the entity classes, they would need to know about the details of shaders.

So how does Cocoa handle comparable situations? Key-value coding. Key-value observation. Bindings.

As it stands, KVC doesn’t really suit our needs. Accessors for relevant properties tend not to return objects. Properties of potential interest to shaders tend to be numbers, vectors, matrices, quaternions (Oolite will convert quaternions to either vectors or rotation matrices for shader bindings) and colours. Colours are represented by objects, but the others are generally not. So I decided to roll my own.

Getting the goods

This turned out to be almost disappointingly simple, although there was a complication arising from the need to support GNUstep as well as Cocoa. First, in order to support multiple types, we need to use -[NSObject methodSignatureForSelector:] to check the return type of the requested method. Then (assuming the type is supported, and other sanity checks), -[NSObject methodForSelector:], which returns an IMP, or function pointer to the method implementation. This function pointer can then be cast to a function pointer with the correct return type, and called to acquire the current value of the attribute in question.

Note: there are some limitations to this approach. In particular, it shortcuts certain dynamic method look-up behaviours. It will not work if the object being bound to (the binding target) is a proxy, and it will not notice if the object’s class changes, or the class’s method table changes. Such changes are made by the key-value observation mechanism used for normal Cocoa bindings. This doesn’t matter in Oolite, and probably won’t matter in the KVO case either, but it is important to be aware of it.

- (BOOL)setBindingTarget:(id)target selector:(SEL)selector
{
    NSMethodSignature       *signature;
    IMP                     method;
    unsigned                argCount;
    ShaderUniformType       type;

    if (target == nil)  return NO;
    if (![target respondsToSelector:selector])  return NO;

    // Get the IMP
    method = [target methodForSelector:selector];
    if (method == NULL)  return NO;

    // Get the method signature
    signature = [target methodSignatureForSelector:selector];
    if (signature == nil)  return NO;

    // All methods have two implicit arguments: self and _msg.
    // Getters have no explicit arguments and therefore have
    // a total of two arguments.
    argCount = [signature numberOfArguments];
    if (argCount != 2)  return NO;

    type = ShaderUniformTypeFromMethodSignature(signature);
    if (type == kShaderUniformTypeInvalid)  return NO;

    // All tests passed – binding is complete.
    _target = target;
    _selector = selector;
    _method = method;
    _type = type;
}

typedef float (*FloatReturnMsgSend)(id, SEL);

- (void)apply
{
    switch (_type)
    {
        case kShaderUniformTypeFloat:
            float fValue = ((FloatReturnMsgSend)_method)(_target, _selector);
            glUniform1fARB(_location, fValue);
            break;

        // Handle other types
        …
    }
}

But, er… what is it?

The only non-standard thing in the above is the function ShaderUniformTypeFromMethodSignature(). It takes an NSMethodSignature and returns an enum specifying the return type of the accessor method we are binding to. The method -[NSMethodSignature methodReturnType] exists for this very purpose. However, this is the source of the aforementioned complication. Cocoa’s implementation returns what you might expect: the @encode() string corresponding to the method’s return type. Therefore, the initial implementation of ShaderUniformTypeFromMethodSignature() in Oolite looked like this:

ShaderUniformType ShaderUniformTypeFromMethodSignature(NSMethodSignature *sig)
{
    const char *type = [sig methodReturnType];
    if (type == NULL)  return kShaderUniformTypeInvalid;

    if (strcmp(type, @encode(float)) == 0)  return kShaderUniformTypeFloat;
    // Handle other types
    …
    else return  kShaderUniformTypeInvalid;
}

However, as the astute reader may have guessed, this did not work under GNUstep. Assiduous link-followers will be quick to point out that the documentation clearly states, “This encoding is implementation-specific, so applications should use it with caution.” In fact, GNUstep seems to return an encoding string for the entire method, that is, the encoding of all the arguments as well as the return type. (I maintain that this is a bug, since it returns different strings for -(int)foo and -(int)bar:(id)frob. However, since we’re only interested in methods with no explicit arguments, that doesn’t matter.) More importantly to the Cocoa programmer, this statement in the documentation means Apple is free to change the Cocoa implementation at any time.

Fortunately, there’s a simple solution: compare to the methodReturnTypes of known methods that return the required type. The final implementation uses a template class which implements a method for each required return type and copies the methodReturnTypes of these methods into an array. The template class pattern may be familiar if you’ve written NSProxys.

Free code!

Oolite’s code is complicated. The code given above is too simple. So here’s some code that’s just right.

The sample application uses a stripped-down version of the shader code from Oolite. It presents a scene consisting of a ball with per-pixel lighting and two moving lights, and controls to set two properties, colour and shininess (a combination of specular exponent and specular intensity). The window controller (cleverly named ExampleController) moves the lights about on a timer.

 


The demo application.

The controls do not affect the scene directly; their values are stored in a model object (ExampleModel) which knows nothing of OpenGL, shaders or lighting. The OpenGL view (ExampleOpenGLView) sets up a shader material and binds the uniforms uColor and uShininess to the appropriate model properties:

_material = [[JAShaderMaterial alloc] initWithVertexShaderSource:vertSource
                                            fragmentShaderSource:fragSource];

// Bind shader uniforms to model attributes.
[_material bindUniform:@"uColor" toObject:_model property:@selector(color)];
[_material bindUniform:@"uShininess" toObject:_model property:@selector(shininess)];

The material creates JAShaderUniform objects to handle the individual uniforms. Now, whenever the shader is used (specifically, when its -apply method is called), the uniform objects pull in their values from the model object. When the slider is moved, the model’s shininess value is changed; when the scene next redraws, the shader’s uShininess uniform reflects the new value. The controller and view don’t need to do anything to update them.

Limitations

The sample app, being a sample app, glosses over some issues. For one thing, binding targets are not retained, to avoid retain cycles. This is the Right Thing when the binding target is the owner of the material, but if it isn’t, you may inadvertently release an object which is bound to. Oolite avoids this by using a proxy-based weak reference system, which is beyond the scope of this article. The sample app also doesn’t bother to check whether its OpenGL context actually supports shaders.

However, the uniform implementation is pretty complete. It supports most of the types Oolite does, namely:

• Signed and unsigned chars, shorts and longs
• floats and doubles
• Vectors, in the form of JAVector structs. In real life, you’d want to use whatever vector struct or class you use for the rest of your application.
• NSPoints (as vec2s)
• NSNumbers (as floats)
• NSColors (as vec4s)

One Oolite feature removed for the example is filtering. Filters supported by Oolite include clamping numbers to the range 0..1, normalizing vectors, and converting quaternions to rotation matrices. These are simple operations that aren’t relevant to the focus of this article.

The sample code may be downloaded here (99 kB) and is distributed under the MIT/X11 License.

Disclaimer

Some of the above is not true. Some is misremembered. Some is glossed over and simplified. The code extracts are all simplified, untested code. Caveat lector.

]]> http://jens.ayton.se/blag/glsl-uniform-bindings-for-cocoa/feed/ 0