lua: Add function to get raw frame data

This can be useful when scripts want to read the entire frame
and pass it on somewhere else (say, write it to a file or use some
library function on it).

automation/v4-docs/get-frame.txt

@@ -69,3 +69,25 @@ Returns: string
   String in ASS format representing the pixel value. e.g. "&H0073FF&"
 
 ---
+
+Get raw BGRA (alpha being irrelevant) data of frame object, whose pixel values
+can then be accessed via LuaJIT's FFI.
+
+The frame data is valid until the frame object is garbage-collected.
+
+Example usage (which does not account for flipped frames for simplicity)
+
+data, pitch = frame:data()
+buf = require("ffi").cast("unsigned char **", data)
+-- Get the R value of the pixel at coordinates (42, 34)
+pix_val = buf[0][34 * pitch + 4 * 42 + 2]
+
+function frame:data()
+
+Returns: 3 values - a userdata object, a number, and a boolean
+  1. Userdata object which can be cast to "unsigned char **" via ffi.cast, a pointer to a pointer to
+     the raw frame data.
+  2. The pitch of the frame data.
+  3. Whether the frame is flipped upside-down.
+
+---

src/auto4_lua.cpp

@@ -259,6 +259,17 @@ namespace {
 		return 1;
 	}
 
+	int FrameData(lua_State *L) {
+		std::shared_ptr<VideoFrame> frame = *check_VideoFrame(L);
+
+		unsigned char **frameData = static_cast<unsigned char **>(lua_newuserdata(L, sizeof(VideoFrame *)));
+		*frameData = frame->data.data();
+		push_value(L, frame->pitch);
+		push_value(L, frame->flipped);
+
+		return 3;
+	}
+
 	int FrameDestroy(lua_State *L) {
 		std::shared_ptr<VideoFrame> *frame = check_VideoFrame(L);
 		frame->~shared_ptr<VideoFrame>();
@@ -283,6 +294,7 @@ namespace {
 			{"height", FrameHeight},
 			{"getPixel", FramePixel},
 			{"getPixelFormatted", FramePixelFormatted},
+			{"data", FrameData},
 			{"__gc", FrameDestroy},
 			{NULL, NULL}
 		};