What is a Result Buffer Data Type? (AutoCAD .net API)

_config.yml

Unfortunately, and unsurprisingly, the documentation is a little sparse on this point. But somewhere deep within the annals of the AutoCAD documentation I found this little beauty:

Here is the documentation

But for you folks who may find that the link does not work, I will also copy and paste verbatim, what is said there:

The ResultBuffer type is a class that mirrors the resbuf struct defined in the ObjectARX SDK. The resbuf struct provides a flexible container for AutoCAD-specific data.

An Autodesk.AutoCAD.DatabaseServices.ResultBuffer class object is used in much the same way as a resbuf chain. You define a ResultBuffer and populate it with a sequence of data pairs. Each pair contains a data type description and a value. In the managed API, these data pairs are instances of theAutodesk.AutoCAD.DatabaseServices.TypedValue class. This utility class serves the same purpose as the restype and resval members of the resbuf struct.

The TypedValue.TypeCode property is a 16-bit integer value that indicates the TypedValue.Value property’s data type. Acceptable TypeCode values depend on the specific use of a ResultBuffer instance. For example, TypeCode values that are suitable for an xrecord definition are not necessarily appropriate for xdata. The Autodesk.AutoCAD.DatabaseServices.DxfCode enum defines codes that accurately describe the full range of possible ResultBuffer data types.

The TypedValue.Value property maps to an instance of System.Object, and theoretically may contain any type of data. However, the Value data must conform to the type indicated by TypeCode to guarantee usable results.

You can prepopulate a ResultBuffer by passing an array of TypedValue objects to its constructor, or you can construct an empty ResultBuffer and later call theResultBuffer::Add() method to append new TypedValue objects. The following example shows a typical ResultBuffer constructor usage:

using (Xrecord rec = new Xrecord())
{
    rec.Data = new ResultBuffer(
        new TypedValue(Convert.ToInt32(DxfCode.Text), "This is a test"),
        new TypedValue(Convert.ToInt32(DxfCode.Int8), 0),
        new TypedValue(Convert.ToInt32(DxfCode.Int16), 1),
        new TypedValue(Convert.ToInt32(DxfCode.Int32), 2),
        new TypedValue(Convert.ToInt32(DxfCode.HardPointerId), db.BlockTableId),
        new TypedValue(Convert.ToInt32(DxfCode.BinaryChunk), new byte[] {0, 1, 2, 3, 4}),
        new TypedValue(Convert.ToInt32(DxfCode.ArbitraryHandle), db.BlockTableId.Handle),
        new TypedValue(Convert.ToInt32(DxfCode.UcsOrg),
        new Point3d(0, 0, 0)));
}

What does all this mean?

You can think of a resbuf container as kinda like a shopping list. And on this list you have to write down each item, and the type of item that it is respectively. e.g. here’s my shopping list

  • Car, Ford Mustang 1973
  • Car, Toyota Corolla 1983
  • Food, Banana
  • Food, Bread
  • Plane, Airbus A280

That’s all it is. When you are reading the resbuf, it’s very handy to know the type of item you are dealing with. Sometimes you may only be looking for food items, so it’s very handy to know whether an item is a food item. If this wasn’t the case then you would have to test each and every single item as to whether you can eat it. That’s why we are required to specify the type of an item as well as the item itself, in the result buffer.

Originally I had likened to the result buffer structure to key value pairs (as in CLR dictionaries) - but danipon suggested that this is strained. A better analogy would be a list of tuples.

Result Buffers are:

  • Made of TypedValue objects.
  • TypedValue objects are like tuples: we are required to specify the type of the object contained therein as well as the object itself. We use a DxfCode to specify the ‘type’ and then we add the object itself (or a reference to one).
  • The value of the TypedValue is any AutoCAD type which corresponds to the DxfCode set as the key.

So then, what is a DfxCode?

It’s an agreed upon standard by which you can communicate an AutoCAD drawing on paper using basically words and numbers.

I hope that’s making some degree of sense? If not I think I will add a diagram to help.

Written on November 30, 2017