- Use System.IO.BinaryReader/BinaryWriter and its' ReadXXX/Write methods to read/write individual fields of the data type T in question.
- Use one of the System.Runtime.InteropServices.Marshal.PtrToStructure/StructureToPtr methods to covert between (pinned) byte arrays (which can be written to and read from System.IO.Stream) and non-generic value types or "formatted class types" via .NET's COM marshalling infrastructure.
- Use a little bit of unsafe code and cast a byte* pointing at the first entry of a pinned byte buffer to a T* so structs of that type T can be written/read by simply dereferencing a pointer.
Sadly, C# cannot constrain type parameters to unmanaged types and, as a consequence, does not support dereferencing generic pointer types. (In C# there is only the struct constraint, but that is not sufficient as a struct might contain fields of reference type.) What that means is that option #3 from above only works for concrete types.
Because F# can constrain a type parameter to be an unmanaged type, I used F# to build the NativeInterop library that—at its core—exposes the possiblity to (unsafely!) dereference generic pointers in C#. This in turn enabled the implementation of some generic extension methods (NativeInterop ≥ v1.4.0) for System.IO.Stream that provide both easy* to use and efficient** methods for reading and writing structured binary files.
A word of warning: The F# unmanaged constrain does not surface in the NativeInterop API if used from C# (and probably VB.NET). Thus the user of NativeInterop has to make sure, that his data types are truly unmanaged! If that is not the case NativeInterop may produce arbitrary garbage!
Example: Writing and Reading Binary STL files
Let's look at a simple example for how to use the aformentioned library methods to handle a simple structured binary file format: STL files essentially contain a description of a triangle mesh (triangulated surface). The exact format of the binary version (there is also an ASCII variant) is described on Wikipedia:- An 80 byte ASCII header, which may contain some descriptive string
- The number of triangles in the mesh as an unsigned 32 bit integer
- For each triangle there is one record of the following format:
- A normal vector made up of three single precions floating point numbers
- Three vertices, each made up of three single precions floating point numbers
- A field called "Attribute byte count" (16 bit unsigned integer); this should usually be zero, but some software may interpret this as color information.
Modeling STL Records in C#
In this example, we will only explicitly model the triangle records. The header information is so simple that it's easier to just directly write out a 80 byte ASCII string.To represent the triangle information, we use the following user-defined unmanaged type(s):
[StructLayout(LayoutKind.Sequential, Pack = 1)] struct STLVector { public readonly float X; public readonly float Y; public readonly float Z; public STLVector(float x, float y, float z) { this.X = x; this.Y = y; this.Z = z; } } [StructLayout(LayoutKind.Sequential, Pack = 1)] struct STLTriangle { // 4 * 3 * 4 byte + 2 byte = 50 byte public readonly STLVector Normal; public readonly STLVector A; public readonly STLVector B; public readonly STLVector C; public readonly ushort AttributeByteCount; public STLTriangle( STLVector normalVec, STLVector vertex1, STLVector vertex2, STLVector vertex3, ushort attr = 0) { Normal = normalVec; A = vertex1; B = vertex2; C = vertex3; AttributeByteCount = attr; } }
Defining a Test Geometry
For testing purposes, we can now define a super-simple triangle mesh, a single tetrahedron:// tetrahedron, vertex order: right hand rule var mesh = new STLTriangle[] { new STLTriangle(new STLVector(0, 0, 0), new STLVector(0, 0, 0), new STLVector(0, 1, 0), new STLVector(1, 0, 0)), new STLTriangle(new STLVector(0, 0, 0), new STLVector(0, 0, 0), new STLVector(0, 0, 1), new STLVector(0, 1, 0)), new STLTriangle(new STLVector(0, 0, 0), new STLVector(0, 0, 0), new STLVector(0, 0, 1), new STLVector(1, 0, 0)), new STLTriangle(new STLVector(0, 0, 0), new STLVector(0, 1, 0), new STLVector(0, 0, 1), new STLVector(1, 0, 0)), };
We leave the normals at zero: Most software will derive the surface normals automatically correctly, if the order in which the vertices of each face are specified follow the right hand rule (i.e. vertices enumerated counter-clockwise when looking at the face from the outside).
Writing STL
Now it's really straightforward to generate a valid STL file from the available data:using (var bw = new BinaryWriter(File.OpenWrite(filename), Encoding.ASCII)) { // Encode the header string as ASCII and put it in a 80 bytes buffer var headerString = "Tetrahedron"; var header = new byte[80]; Encoding.ASCII.GetBytes(headerString, 0, headerString.Length, header, 0); bw.Write(header); // write #triangles bw.Write(mesh.Length); // use extension method from NativeInterop.Stream to write out the mesh data bw.BaseStream.WriteUnmanagedStructRange(mesh); }
And here we have it, our, ahem, "beautiful" tetrahedron rendered in MeshLab:
Note how all the surface normals are sticking outward.
Reading STL
By using the ReadStructRange<T> extension method, reading binary STL data is just as simple:string header; STLTriangle[] mesh; using (var br = new BinaryReader(File.OpenRead(filename), Encoding.ASCII)) { header = Encoding.ASCII.GetString(br.ReadBytes(80)); var triCount = br.ReadUInt32(); mesh = br.BaseStream.ReadUnmanagedStructRange<STLTriangle>((int)triCount); }
Conclusion
Reading and writing simple structured binary data is easy using NativeInterop.Stream. Get it now from NuGet! For reporting bugs or suggesting new features, please use the BitBucket issue tracker.*Easy, because the user of the library doesn't have to fiddle with unsafe code.
**Efficient, because under the hood it boils down to a generic version of option #3 with zero marshalling overhead.
