OFPFileFormat - Revision history

Patapom at 17:49, 9 May 2011

2011-05-09T17:49:37Z

Patapom at 17:45, 9 May 2011

2011-05-09T17:45:10Z

Patapom at 17:41, 9 May 2011

2011-05-09T17:41:00Z

Patapom at 17:03, 9 May 2011

2011-05-09T17:03:05Z

Patapom at 16:49, 9 May 2011

2011-05-09T16:49:59Z

Patapom at 16:42, 9 May 2011

2011-05-09T16:42:51Z

Patapom at 16:27, 9 May 2011

2011-05-09T16:27:13Z

Patapom at 16:11, 9 May 2011

2011-05-09T16:11:17Z

Patapom at 16:03, 9 May 2011

2011-05-09T16:03:45Z

Patapom at 15:59, 9 May 2011

2011-05-09T15:59:30Z

@@ Line 179: / Line 179: @@
 * a '''LENS_OBJECT_SOLO''' atom whose ID=0x04 and value is a boolean telling if the object is displayed alone (true) or displayed with the others (false)
-All we have to do then is to create an instance of the appropriate LensObject object with its name and Hide/Solo flags, then de-serialize its field.
+All we have to do then is to create an instance of the appropriate LensObject object with its name and Hide/Solo flags, then de-serialize its fields.
 We stop reading the block when we encounter an atom whose ID=0x3E8 which is the end marker.

@@ Line 71: / Line 71: @@
 == Fields ==
 '''Fields''' are composed of 4 atoms (that I know of) and are like a super-atom of some sort.
@@ Line 88: / Line 90: @@
 Value Atom => Atom ID=0x34 whose value is the value of the field (told you it was crazy !)
 Marker Atom => Atom ID=0x7D0 that marks the end of the field
 === Field ID ===
@@ Line 123: / Line 123: @@
 = Reading the File =
 So basically, instead of using a standard BinaryReader to read the file, you start by reading the header then all you're going to read are Atoms after that. It's a bit like if the BinaryReader transformed into an ''AtomReader'' instead.
 Here is the general file structure :
 And this is how you read the file :

@@ Line 1: / Line 1: @@
 = The Optical Flares Preset file format =
-It could have been a simple XML format but no ! The guys at Video Copilot knew I would be coming for them at some point, so they devised the most annoying file format on Earth !
+It could have been a simple XML format but no ! The guys at Video Copilot knew I would be coming for them, so they devised the most annoying file format on Earth !
 I suppose it's one of these companies that imagine they can create some products that are "Future Proof". Moohahaha ! Sorry guys, but nothing's future proof : ask the guys in nuclear waste storage...
-Moreover, their products are called ''Video Copilot.Net'' so you may think they take advantage of the smart serialization helpers that can be used with the .Net framework, like XML with XSLT for example. But that would be too easy.
+Moreover, their products are called ''Video Copilot.Net'' so you may think they would take advantage of the smart serialization helpers that can be used with the .Net framework, like XML with XSLT for example. But that would be too easy.
 The guys at VC decided to create their own future-proof-tarot-reading binary format with unique IDs and shit.
@@ Line 29: / Line 32: @@
 Here is the structure of an Atom :
 WORD = Atom Type
-WORLD = Atom Run Length '''L'''
+WORD = Atom Run Length '''L'''
   '''L''' BYTES = Atom Value
-At which point, I was really wondering if the guys at VC weren't a bit crazy in the coconut because, usually, when you create a binary file format and deliberately choose not to use XML, that means you're after size optimization. But here, you have to know that Atoms that host values have a minimum run-length of 32 bytes. Even a simple boolean ! That means that, in order to store a boolean, you must write 2 bytes (Atom Type) + 2 bytes (Run Length = 32) + 32 bytes (the actual boolean value) = '''36 bytes total''' ! (but who am I to judge ? In order to be actually future-proof, we must not eliminate the hypothesis that tomorrow, perhaps, booleans will be stored on 256 bits) (you never really know, that's the beauty with future)
+At which point, I was really wondering if the guys at VC weren't a bit crazy in the coconut because, usually, when you create a binary file format and deliberately choose not to use XML, that means you're after size optimization. But here, you have to know that Atoms that host values have a minimum run-length of 32 bytes. Even a simple boolean ! That means that, in order to store a boolean, you must write 2 bytes (Atom Type) + 2 bytes (Run Length = 32) + 32 bytes (the actual boolean value) = '''36 bytes total''' ! (but who am I to judge ? In order to be actually future-proof, we must not eliminate the hypothesis that tomorrow, perhaps, booleans will be stored on 256 bits) (you never really know, that's the beauty with the future)
@@ Line 56: / Line 59: @@
-I created an Atom class that simply reads Atoms from a standard System.IO.BinaryReader. The run-length encoded Atom Value is stored as a variant type that can be of the following recognized types :
+I created an Atom class that simply reads Atoms from a standard System.IO.BinaryReader. The run-length encoded Atom Value is stored as a variant type that can be one of the following recognized types :
   BOOLEAN
   INTEGER / ENUM
@@ Line 78: / Line 81: @@
 Typically, an object (GeneralParameters or LensObject) starts with a header, a bunch of fields and a footer or ''end marker''.
 Here is the structure of a Field (remember we're now dealing with Atoms, not simple types like float or integer anymore) :
@@ Line 84: / Line 88: @@
 Value Atom => Atom ID=0x34 whose value is the value of the field (told you it was crazy !)
 Marker Atom => Atom ID=0x7D0 that marks the end of the field
 === Field ID ===
-The '''Field ID''' is unique and corresponds to the ID of some field in your class.
+The '''Field ID''' is unique and corresponds to the ID of some '''actual field''' in your class.
 For the purpose of automatically binding the fields from the file and the fields in a C# class, I created an "ID" attribute so when I create a field in my C# class, I also attach it its ID which corresponds to the ID that is read from disk.
@@ Line 108: / Line 114: @@
   BOOL = 4, a BOOLEAN field
   ENUM_STRING = 5, an enum value (INT) + the enum name (STRING)
-  SEPARATOR = 6, a useless separator which corresponds to the groups of fields that you can see in the plug-in ("Common Settings" is a group, "Dynamic Triggering" is another group, each group's fields are separated by a SEPARATOR field)
+  SEPARATOR = 6, a useless separator which corresponds to the groups of fields that you can see in the plug-in
 === Field Value ===
@@ Line 119: / Line 126: @@
 So basically, instead of using a standard BinaryReader to read the file, you start by reading the header then all you're going to read are Atoms after that. It's a bit like if the BinaryReader transformed into an ''AtomReader'' instead.
-Here is how you read the file :
+Here is the general file structure :
 == Descriptor Atom ==

← Older revision		Revision as of 17:03, 9 May 2011
Line 175:		Line 175:
	== Automatic Deserialization of Fields ==		== Automatic Deserialization of Fields ==

−	~~List FieldInfos~~, List IDs ~~=> Attach~~	+	As we have summarily described earlier, de-serialization of fields is made quite simple via the '''Field ID'''s and the '''IDAttribute''' attached to the physical class fields.
		+
		+	The de-serialization of fields exists as a single method that lies in the base class of all de-serializable objects (i.e. GeneralParameters and LensObjects alike).
		+
		+	This methods does the following :
		+	# // List all the fields in the object to de-serialize via reflection
		+	## For each System.Reflection.FieldInfo in our class
		+	### Retrieve its custom '''ID''' atribute
		+	### If no such attribute → throw exception (we don't want to have fields without an ID !)
		+	### Add the ID of the field to the map of '''ID → Field'''
		+	### If the ID is already registered in the map → throw exception (we don't accept duplicate IDs !)
		+	# // Read the fields from the OFP file
		+	## While we haven't encountered an end marker
		+	### Read the next field from file
		+	### Retrieve the actual class field to de-serialize to via the '''ID → Field''' map
		+	### If no such ID exists in the map → throw exception (we need a field to de-serialize to !)
		+	### De-serialize the field from file into the class field

@@ Line 120: / Line 120: @@
 Here is how you read the file :
 == Descriptor Atom ==
@@ Line 131: / Line 130: @@
-== General Parameters Block ==
+=== Reading the General Parameters Block ===
-Say we encountered an atom with ID=0xBB8, we then can read all the fields in that block.
+All we have to do is to create an instance of the General Parameters class, then de-serialize its fields.
 The field groups are :
@@ Line 144: / Line 145: @@
 We stop reading the block when we encounter an atom whose ID=0xFA0 which is the end marker.
-== Lens Object ==
+=== Reading a Lens Object ===
 Say we encountered an atom with ID=0x01, this marks the beginning of a Lens Object block.
-This is followed by :
+This Atom also gives us (via its INT value) the type of lens object that is described further. Here are the 12 supported types :
 * a '''LENS_OBJECT_NAME''' atom whose ID=0x02 and value is the name of the lens object (a string)
 * a '''LENS_OBJECT_HIDE''' atom whose ID=0x03 and value is a boolean telling if the object is hidden (true) or visible (false)
 * a '''LENS_OBJECT_SOLO''' atom whose ID=0x04 and value is a boolean telling if the object is displayed alone (true) or displayed with the others (false)
 We stop reading the block when we encounter an atom whose ID=0x3E8 which is the end marker.
-== Automatic Deserialization ==
+== Automatic Deserialization of Fields ==
 List FieldInfos, List IDs => Attach

@@ Line 83: / Line 83: @@
 Type Atom => Atom ID=0x33 whose value as INT is the TYPE of the field
 Value Atom => Atom ID=0x34 whose value is the value of the field (told you it was crazy !)
 === Field ID ===
@@ Line 93: / Line 94: @@
   class MyLensObject
+  {
-    [ID( 0x3F )] public float    SomeValue;
+    [ID( 0x3F )] public float    SomeValue;  // So we know that when we read a field from the file whose ID is 0x3F, we should de-serialize it here...
+  }
@@ Line 108: / Line 109: @@
   ENUM_STRING = 5, an enum value (INT) + the enum name (STRING)
   SEPARATOR = 6, a useless separator which corresponds to the groups of fields that you can see in the plug-in ("Common Settings" is a group, "Dynamic Triggering" is another group, each group's fields are separated by a SEPARATOR field)
@@ Line 113: / Line 118: @@
 So basically, instead of using a standard BinaryReader to read the file, you start by reading the header then all you're going to read are Atoms after that. It's a bit like if the BinaryReader transformed into an ''AtomReader'' instead.
@@ Line 118: / Line 125: @@
 The main loop of the file reader reads a single Atom that will either be :
-* The GeneralParametersBlock header (Atom Type = 0xBB8 as written above), in which case we then read the GeneralParameters
+* The GeneralParametersBlock header (Atom ID=0xBB8 as written above), in which case we then read the GeneralParameters
-* The LensObjectDescriptor header (Atom Type = 0x01 as written above), in which case we then read a LensObject
+* The LensObjectDescriptor header (Atom ID=0x01 as written above), in which case we then read a LensObject
 == General Parameters Block ==

@@ Line 75: / Line 75: @@
 There are fields in 2 types of objects :
 * General Parameters object, which are parameters global to the lens flare
-* Lens Objects, which describe the lens effects existing in the lens flare (a lens object is one of the 12 object types described in [[Lens_Flares]])
+* Lens Objects, which describe the lens effects existing in the lens flare (a lens object is one of the 12 object types described in the [[Lens_Flares#The_Lens_Flare_Class|Lens Flare]] page)
@@ Line 93: / Line 125: @@
 = LensFlare Class =
-Check the [[Lens_Flares#The_Lens_Flare_Class]] page to get my free LensFlare class in C# that is able to read OFP files.
+Check the [[Lens_Flares#The_Lens_Flare_Class|Lens Flare]] page to get my free LensFlare class in C# that is able to read OFP files.

← Older revision		Revision as of 16:03, 9 May 2011
Line 32:		Line 32:
	'''L''' BYTES = Atom Value		'''L''' BYTES = Atom Value

−	At which point, I was really wondering if the guys at VC weren't a bit crazy in the coconut because, usually, when you create a binary file format and deliberately choose not to use XML, that means you're after size optimization. But here, you have to know that Atoms that host values have a minimum run-length of 32 bytes. Even a simple boolean ! That means that, in order to store a boolean, you must write 2 bytes (Atom Type) + 2 bytes (Run Length = 32) + 32 bytes (the actual boolean value) = '''36 bytes total''' !	+	At which point, I was really wondering if the guys at VC weren't a bit crazy in the coconut because, usually, when you create a binary file format and deliberately choose not to use XML, that means you're after size optimization. But here, you have to know that Atoms that host values have a minimum run-length of 32 bytes. Even a simple boolean ! That means that, in order to store a boolean, you must write 2 bytes (Atom Type) + 2 bytes (Run Length = 32) + 32 bytes (the actual boolean value) = '''36 bytes total''' ! (but who am I to judge ? In order to be actually future-proof, we must not eliminate the hypothesis that tomorrow, perhaps, boolean will be stored on 256 bits) (you never really know, that's the beauty with future)

@@ Line 30: / Line 30: @@
 WORD = Atom Type
 WORLD = Atom Run Length '''L'''
-  '''L''' BYTES
+  '''L''' BYTES = Atom Value
-I have isolated the following Atom types :
+At which point, I was really wondering if the guys at VC weren't a bit crazy in the coconut because, usually, when you create a binary file format and deliberately choose not to use XML, that means you're after size optimization. But here, you have to know that Atoms that host values have a minimum run-length of 32 bytes. Even a simple boolean ! That means that, in order to store a boolean, you must write 2 bytes (Atom Type) + 2 bytes (Run Length = 32) + 32 bytes (the actual boolean value) = '''36 bytes total''' !
   // Field atoms
   FIELD_ID = 0x32,
@@ Line 51: / Line 54: @@
   GLOBAL_PARAMS_END = 0xFA0,
   LENS_OBJECT_END = 0x3E8,