The Core AdvLib Functions method is suitable for people who want to have a full and low-level control over the created file. To be able to use effectively the core level AdvLib functions however one also requires a full understanding of the ADV file format. A simpler and less involved method for creating an ADV file using the AdvRecorder is also available.
Even that the code samples below are in C# they can also be used as a reference for C and C++ programming. The names of the C# core functions is identical to those of the C functions exported by the core library.
The sample code below demonstrates the minimum code required to create a new ADV file using the lower level functions of AdvLib. It saves 10 video frames in a 16-bit uncompressed image layout format and simulates an exposure of 0.5 sec. Please note that the timing accuracy, according to the standard, is provided in nanoseconds when passed to the DefineStatusSection() method. This code doesn't do any error checking.
The UTC timestamp for the beginning the exposure of the video frame and the exposure duration are provided as the 2-nd and 3-th argument of AdvLib.BeginFrame(). The AdvTimeStamp.FromDateTime().NanosecondsAfterAdvZeroEpoch method is used to convert the .NET DateTime to the format used in the ADV file format.
fileName = @"C:\hello-world.adv";
const uint MILLI_TO_NANO = 1000000;
const byte IMAGE_LAYOUT_ID = 1;
const int WIDTH = 800;
const int HEIGHT = 600;
Adv.AdvLib.NewFile(fileName);
Adv.AdvLib.AddOrUpdateFileTag("FSTF-TYPE", "ADV");
Adv.AdvLib.AddOrUpdateFileTag("ADV-VERSION", "2");
Adv.AdvLib.DefineImageSection(WIDTH, HEIGHT, 16);
Adv.AdvLib.DefineImageLayout(IMAGE_LAYOUT_ID, "FULL-IMAGE-RAW", "UNCOMPRESSED", 16);
Adv.AdvLib.DefineStatusSection(1 * MILLI_TO_NANO /* 1ms */);
// TODO: Get the real actual timestamps and exposure
DateTime startTime = DateTime.UtcNow;
uint exposureMilliseconds = 500;
for (int i = 0; i < 10; i++)
{
// TODO: Get the real actual timestamps and exposure
DateTime exposureStartTime = startTime.AddMilliseconds(exposureMilliseconds * i);
Adv.AdvLib.BeginFrame(0,
AdvTimeStamp.FromDateTime(exposureStartTime).NanosecondsAfterAdvZeroEpoch,
MILLI_TO_NANO * exposureMilliseconds);
// TODO: Get the real pixels here
ushort[] pixels = new ushort[WIDTH * HEIGHT];
Adv.AdvLib.FrameAddImage(IMAGE_LAYOUT_ID, pixels, 16);
Adv.AdvLib.EndFrame();
}
Adv.AdvLib.EndFile();
A better version of the code above which does error checking using the AdvError.Check() method. By default this method will throw an AdvCoreException. The static fields AdvError.ShowMessageBoxErrorMessage and AdvError.ThrowError can be used to configure the behaviour of AdvError.Check(). In the exampe below any error messages that might occur are configured to be displayed in a message box.
fileName = @"C:\hello-world.adv";
const uint MILLI_TO_NANO = 1000000;
const byte IMAGE_LAYOUT_ID = 1;
const int WIDTH = 800;
const int HEIGHT = 600;
AdvError.ShowMessageBoxErrorMessage = true;
AdvError.Check(Adv.AdvLib.NewFile(fileName));
AdvError.Check(Adv.AdvLib.AddOrUpdateFileTag("FSTF-TYPE", "ADV"));
AdvError.Check(Adv.AdvLib.AddOrUpdateFileTag("ADV-VERSION", "2"));
AdvError.Check(Adv.AdvLib.DefineImageSection(WIDTH, HEIGHT, 16));
AdvError.Check(Adv.AdvLib.DefineImageLayout(
IMAGE_LAYOUT_ID, "FULL-IMAGE-RAW", "UNCOMPRESSED", 16));
AdvError.Check(Adv.AdvLib.DefineStatusSection(1 * MILLI_TO_NANO /* 1ms */));
// TODO: Get the real actual timestamps and exposure
DateTime startTime = DateTime.UtcNow;
uint exposureMilliseconds = 500;
for (int i = 0; i < 10; i++)
{
// TODO: Get the real actual timestamps and exposure
DateTime exposureStartTime = startTime.AddMilliseconds(exposureMilliseconds * i);
AdvError.Check(Adv.AdvLib.BeginFrame(0,
AdvTimeStamp.FromDateTime(exposureStartTime).NanosecondsAfterAdvZeroEpoch,
MILLI_TO_NANO * exposureMilliseconds));
// TODO: Get the real pixels here
ushort[] pixels = new ushort[WIDTH * HEIGHT];
AdvError.Check(Adv.AdvLib.FrameAddImage(IMAGE_LAYOUT_ID, pixels, 16));
AdvError.Check(Adv.AdvLib.EndFrame());
}
AdvError.Check(Adv.AdvLib.EndFile());