API rework, round 2.

Bindings still probably broken: Python, Java, AS3, C#, Matlab, Ruby

Signed-off-by: Drew Fisher <drew.m.fisher@gmail.com> (zarvox)

examples/glview.c

@@ -338,9 +338,8 @@ void *freenect_threadfunc(void *arg)
 	freenect_set_led(f_dev,LED_RED);
 	freenect_set_depth_callback(f_dev, depth_cb);
 	freenect_set_video_callback(f_dev, rgb_cb);
-	freenect_set_video_format(f_dev, current_format);
-	freenect_set_video_resolution(f_dev, FREENECT_RESOLUTION_MEDIUM);
-	freenect_set_depth_format(f_dev, FREENECT_DEPTH_11BIT);
+	freenect_set_video_mode(f_dev, freenect_find_video_mode(FREENECT_RESOLUTION_MEDIUM, current_format));
+	freenect_set_depth_mode(f_dev, freenect_find_depth_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_DEPTH_11BIT));
 	freenect_set_video_buffer(f_dev, rgb_back);
 
 	freenect_start_depth(f_dev);
@@ -364,7 +363,7 @@ void *freenect_threadfunc(void *arg)
 
 		if (requested_format != current_format) {
 			freenect_stop_video(f_dev);
-			freenect_set_video_format(f_dev, requested_format);
+			freenect_set_video_mode(f_dev, freenect_find_video_mode(FREENECT_RESOLUTION_MEDIUM, requested_format));
 			freenect_start_video(f_dev);
 			current_format = requested_format;
 		}

examples/hiview.c

@@ -72,8 +72,8 @@ int freenect_led;
 
 freenect_video_format requested_format = FREENECT_VIDEO_RGB;
 freenect_video_format current_format = FREENECT_VIDEO_RGB;
-freenect_video_resolution requested_resolution = FREENECT_RESOLUTION_HIGH;
-freenect_video_resolution current_resolution = FREENECT_RESOLUTION_HIGH;
+freenect_resolution requested_resolution = FREENECT_RESOLUTION_HIGH;
+freenect_resolution current_resolution = FREENECT_RESOLUTION_HIGH;
 
 pthread_cond_t gl_frame_cond = PTHREAD_COND_INITIALIZER;
 int got_rgb = 0;
@@ -133,7 +133,7 @@ void DrawVideoScene()
 
 	pthread_mutex_lock(&video_mutex);
 
-	freenect_frame_size frame_size = freenect_get_video_frame_size(current_format, current_resolution);
+	freenect_frame_mode frame_mode = freenect_get_current_video_mode(f_dev);
 
 	if (got_rgb) {
 		uint8_t *tmp = rgb_front;
@@ -151,16 +151,16 @@ void DrawVideoScene()
 
 	glBindTexture(GL_TEXTURE_2D, gl_rgb_tex);
 	if (current_format == FREENECT_VIDEO_RGB || current_format == FREENECT_VIDEO_YUV_RGB) {
-		glTexImage2D(GL_TEXTURE_2D, 0, 3, frame_size.width, frame_size.height, 0, GL_RGB, GL_UNSIGNED_BYTE, rgb_front);
+		glTexImage2D(GL_TEXTURE_2D, 0, 3, frame_mode.width, frame_mode.height, 0, GL_RGB, GL_UNSIGNED_BYTE, rgb_front);
 	} else {
-		glTexImage2D(GL_TEXTURE_2D, 0, 1, frame_size.width, frame_size.height, 0, GL_LUMINANCE, GL_UNSIGNED_BYTE, rgb_front);
+		glTexImage2D(GL_TEXTURE_2D, 0, 1, frame_mode.width, frame_mode.height, 0, GL_LUMINANCE, GL_UNSIGNED_BYTE, rgb_front);
 	}
 	glBegin(GL_TRIANGLE_FAN);
 	glColor4f(1.0f, 1.0f, 1.0f, 1.0f);
 	glTexCoord2f(0, 0); glVertex3f(0,0,0);
-	glTexCoord2f(1, 0); glVertex3f(frame_size.width,0,0);
-	glTexCoord2f(1, 1); glVertex3f(frame_size.width,frame_size.height,0);
-	glTexCoord2f(0, 1); glVertex3f(0,frame_size.height,0);
+	glTexCoord2f(1, 0); glVertex3f(frame_mode.width,0,0);
+	glTexCoord2f(1, 1); glVertex3f(frame_mode.width,frame_mode.height,0);
+	glTexCoord2f(0, 1); glVertex3f(0,frame_mode.height,0);
 	glEnd();
 
 	glutSwapBuffers();
@@ -211,7 +211,7 @@ void keyPressed(unsigned char key, int x, int y)
 			}
 		}
 		glutSetWindow(video_window);
-		freenect_frame_size s = freenect_get_video_frame_size(requested_format, requested_resolution);
+		freenect_frame_mode s = freenect_find_video_mode(requested_resolution, requested_format);
 		glutReshapeWindow(s.width, s.height);
 	}
 	if (key == 'd') { // Toggle depth camera.
@@ -272,9 +272,9 @@ void *gl_threadfunc(void *arg)
 	glutKeyboardFunc(&keyPressed);
 	InitGL(640, 480);
 
-	freenect_frame_size frame = freenect_get_video_frame_size(current_format, current_resolution);
+	freenect_frame_mode mode = freenect_find_video_mode(current_resolution, current_format);
 	glutInitWindowPosition(640,0);
-	glutInitWindowSize(frame.width, frame.height);
+	glutInitWindowSize(mode.width, mode.height);
 	video_window = glutCreateWindow("Video");
 
 	glutDisplayFunc(&DrawVideoScene);
@@ -283,7 +283,7 @@ void *gl_threadfunc(void *arg)
 	glutKeyboardFunc(&keyPressed);
 
 	InitGL(640, 480);
-	ReSizeGLScene(frame.width, frame.height);
+	ReSizeGLScene(mode.width, mode.height);
 
 	glutMainLoop();
 
@@ -362,12 +362,11 @@ void *freenect_threadfunc(void *arg)
 	freenect_set_led(f_dev,LED_RED);
 	freenect_set_depth_callback(f_dev, depth_cb);
 	freenect_set_video_callback(f_dev, video_cb);
-	freenect_set_video_format(f_dev, current_format);
-	freenect_set_video_resolution(f_dev, current_resolution);
-	freenect_set_depth_format(f_dev, FREENECT_DEPTH_11BIT);
-	rgb_back = (uint8_t*)malloc(freenect_get_video_frame_size(current_format, current_resolution).bytes);
-	rgb_mid = (uint8_t*)malloc(freenect_get_video_frame_size(current_format, current_resolution).bytes);
-	rgb_front = (uint8_t*)malloc(freenect_get_video_frame_size(current_format, current_resolution).bytes);
+	freenect_set_video_mode(f_dev, freenect_find_video_mode(current_resolution, current_format));
+	freenect_set_depth_mode(f_dev, freenect_find_depth_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_DEPTH_11BIT));
+	rgb_back = (uint8_t*)malloc(freenect_find_video_mode(current_resolution, current_format).bytes);
+	rgb_mid = (uint8_t*)malloc(freenect_find_video_mode(current_resolution, current_format).bytes);
+	rgb_front = (uint8_t*)malloc(freenect_find_video_mode(current_resolution, current_format).bytes);
 	freenect_set_video_buffer(f_dev, rgb_back);
 
 	freenect_start_depth(f_dev);
@@ -378,15 +377,14 @@ void *freenect_threadfunc(void *arg)
 		status = freenect_process_events(f_ctx);
 		if (requested_format != current_format || requested_resolution != current_resolution) {
 			freenect_stop_video(f_dev);
-			freenect_set_video_format(f_dev, requested_format);
-			freenect_set_video_resolution(f_dev, requested_resolution);
+			freenect_set_video_mode(f_dev, freenect_find_video_mode(requested_resolution, requested_format));
 			pthread_mutex_lock(&video_mutex);
 			free(rgb_back);
 			free(rgb_mid);
 			free(rgb_front);
-			rgb_back = (uint8_t*)malloc(freenect_get_video_frame_size(requested_format, requested_resolution).bytes);
-			rgb_mid = (uint8_t*)malloc(freenect_get_video_frame_size(requested_format, requested_resolution).bytes);
-			rgb_front = (uint8_t*)malloc(freenect_get_video_frame_size(requested_format, requested_resolution).bytes);
+			rgb_back = (uint8_t*)malloc(freenect_find_video_mode(requested_resolution, requested_format).bytes);
+			rgb_mid = (uint8_t*)malloc(freenect_find_video_mode(requested_resolution, requested_format).bytes);
+			rgb_front = (uint8_t*)malloc(freenect_find_video_mode(requested_resolution, requested_format).bytes);
 			current_format = requested_format;
 			current_resolution = requested_resolution;
 			pthread_mutex_unlock(&video_mutex);

fakenect/fakenect.c

@@ -194,7 +194,7 @@ int freenect_process_events(freenect_context *ctx)
 			if (cur_rgb_cb && rgb_running) {
 				void *cur_rgb = skip_line(data);
 				if (rgb_buffer) {
-					memcpy(rgb_buffer, cur_rgb, freenect_get_video_frame_size(FREENECT_VIDEO_RGB, FREENECT_RESOLUTION_MEDIUM).bytes);
+					memcpy(rgb_buffer, cur_rgb, freenect_find_video_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_VIDEO_RGB).bytes);
 					cur_rgb = rgb_buffer;
 				}
 				cur_rgb_cb(fake_dev, cur_rgb, timestamp);

fakenect/record.c

@@ -119,7 +119,7 @@ void depth_cb(freenect_device *dev, void *depth, uint32_t timestamp)
 
 void rgb_cb(freenect_device *dev, void *rgb, uint32_t timestamp)
 {
-	dump('r', timestamp, rgb, freenect_get_current_video_frame_size(dev).bytes);
+	dump('r', timestamp, rgb, freenect_get_current_video_mode(dev).bytes);
 }
 
 void init()
@@ -135,10 +135,9 @@ void init()
 		printf("Error: Cannot get device\n");
 		return;
 	}
-	freenect_set_depth_format(dev, FREENECT_DEPTH_11BIT);
+	freenect_set_depth_mode(dev, freenect_find_depth_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_DEPTH_11BIT));
 	freenect_start_depth(dev);
-	freenect_set_video_format(dev, FREENECT_VIDEO_RGB);
-	freenect_set_video_resolution(dev, FREENECT_RESOLUTION_MEDIUM);
+	freenect_set_video_mode(dev, freenect_find_video_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_VIDEO_RGB));
 	freenect_start_video(dev);
 	freenect_set_depth_callback(dev, depth_cb);
 	freenect_set_video_callback(dev, rgb_cb);

include/libfreenect.h

@@ -40,24 +40,29 @@ extern "C" {
 
 #define FREENECT_COUNTS_PER_G 819 /**< Ticks per G for accelerometer as set per http://www.kionix.com/Product%20Sheets/KXSD9%20Product%20Brief.pdf */
 
-/// Structure to give information about the width and height of a
-/// frame, as well as the total number of bytes needed to hold a
-/// single frame.  Negative values for width and height indicate
-/// an invalid video format and resolution combination, as does
-/// a value of 0 for bytes.
+/// Structure to give information about the width, height, bitrate,
+/// framerate, and buffer size of a frame in a particular mode, as
+/// well as the total number of bytes needed to hold a single frame.
 typedef struct {
-	int width;  /**< Width of this frame, in pixels */
-	int height; /**< Height of this frame, in pixels */
-	int bytes;  /**< Total number of bytes needed to hold a single frame at the given resolution and pixel format */
-} freenect_frame_size;
+	uint32_t reserved;               /**< unique ID used internally.  The meaning of values may change without notice.  Don't touch or depend on the contents of this field.  We mean it. */
+	int is_valid;               /**< If 0, this freenect_frame_mode is invalid and does not describe a supported mode.  Otherwise, the frame_mode is valid. */
+	int bytes;                  /**< Total buffer size in bytes to hold a single frame of data.  Should be equivalent to width * height * (data_bits_per_pixel+padding_bits_per_pixel) / 8 */
+	int width;                  /**< Width of the frame, in pixels */
+	int height;                 /**< Height of the frame, in pixels */
+	int data_bits_per_pixel;    /**< Number of bits of information needed for each pixel */
+	int padding_bits_per_pixel; /**< Number of bits of padding for alignment used for each pixel */
+	int framerate;              /**< Approximate expected frame rate, in Hz */
+} freenect_frame_mode ;
 
 /// Enumeration of available resolutions.
 /// Not all available resolutions are actually supported for all video formats.
+/// Frame modes may not perfectly match resolutions.  For instance,
+/// FREENECT_RESOLUTION_MEDIUM is 640x488 for the IR camera.
 typedef enum {
 	FREENECT_RESOLUTION_LOW    = 0, /**< QVGA - 320x240 */
 	FREENECT_RESOLUTION_MEDIUM = 1, /**< VGA  - 640x480 */
 	FREENECT_RESOLUTION_HIGH   = 2, /**< SXGA - 1280x1024 */
-} freenect_video_resolution;
+} freenect_resolution;
 
 /// Enumeration of video frame information states.
 /// See http://openkinect.org/wiki/Protocol_Documentation#RGB_Camera for more information.
@@ -271,26 +276,6 @@ FREENECTAPI void freenect_set_depth_callback(freenect_device *dev, freenect_dept
  */
 FREENECTAPI void freenect_set_video_callback(freenect_device *dev, freenect_video_cb cb);
 
-/**
- * Set the format for depth information
- *
- * @param dev Device to set depth information format for
- * @param fmt Format of depth information. See freenect_depth_format enum.
- *
- * @return 0 on success, < 0 on error
- */
-FREENECTAPI int freenect_set_depth_format(freenect_device *dev, freenect_depth_format fmt);
-
-/**
- * Set the format for video information
- *
- * @param dev Device to set video information format for
- * @param fmt Format of video information. See freenect_video_format enum.
- *
- * @return 0 on success, < 0 on error
- */
-FREENECTAPI int freenect_set_video_format(freenect_device *dev, freenect_video_format fmt);
-
 /**
  * Set the buffer to store depth information to. Size of buffer is
  * dependant on depth format. See FREENECT_DEPTH_*_SIZE defines for
@@ -429,40 +414,105 @@ FREENECTAPI int freenect_set_led(freenect_device *dev, freenect_led_options opti
 FREENECTAPI void freenect_get_mks_accel(freenect_raw_tilt_state *state, double* x, double* y, double* z);
 
 /**
- * Return the resolution implied and buffer size needed for the given
- * pixel format and resolution enum values.
+ * Get the number of video camera modes supported by the driver.  This includes both RGB and IR modes.
  *
- * @param fmt Video format (pixel format) to return information about
- * @param res Resolution enum value to return information about
+ * @return Number of video modes supported by the driver
+ */
+FREENECTAPI int freenect_get_video_mode_count();
+
+/**
+ * Get the frame descriptor of the nth supported video mode for the
+ * video camera.
  *
- * @return Frame information structure, containing width, height, and
- * bytes-per-frame.  If width, height, or bytes is 0, the requested
- * format/resolution combination is unsupported and can be considered
- * invalid.
+ * @param n Which of the supported modes to return information about
+ *
+ * @return A freenect_frame_mode describing the nth video mode
  */
-FREENECTAPI freenect_frame_size freenect_get_video_frame_size(freenect_video_format fmt, freenect_video_resolution res);
+FREENECTAPI const freenect_frame_mode freenect_get_video_mode(int mode_num);
 
 /**
- * Convenience function to return the resolution and buffer size for
- * the current pixel format and resolution of a given freenect device.
+ * Get the frame descriptor of the current video mode for the specified
+ * freenect device.
  *
- * @param dev Device to return current frame format information about
+ * @param dev Which device to return the currently-set video mode for
  *
- * @return Frame information structure.  As in freenect_get_video_frame_size(),
- * if width, height, or bytes is 0, the requested format/resolution
- * combination is unsupported.
+ * @return A freenect_frame_mode describing the current video mode of the specified device
  */
-FREENECTAPI freenect_frame_size freenect_get_current_video_frame_size(freenect_device *dev);
+FREENECTAPI const freenect_frame_mode freenect_get_current_video_mode(freenect_device *dev);
 
 /**
- * Set which resolution the video stream should run at for a given freenect device.
+ * Convenience function to return a mode descriptor matching the
+ * specified resolution and video camera pixel format, if one exists.
  *
- * @param dev Device for which to set video stream resolution
- * @param res Desired stream resolution
+ * @param res Resolution desired
+ * @param fmt Pixel format desired
  *
- * @return 0 on success, < 0 on error.
+ * @return A freenect_frame_mode that matches the arguments specified, if such a valid mode exists; otherwise, an invalid freenect_frame_mode.
+ */
+FREENECTAPI const freenect_frame_mode freenect_find_video_mode(freenect_resolution res, freenect_video_format fmt);
+
+/**
+ * Sets the current video mode for the specified device.  If the
+ * freenect_frame_mode specified is not one provided by the driver
+ * e.g. from freenect_get_video_mode() or freenect_find_video_mode()
+ * then behavior is undefined.  The current video mode cannot be
+ * changed while streaming is active.
+ *
+ * @param dev Device for which to set the video mode
+ * @param mode Frame mode to set
+ *
+ * @return 0 on success, < 0 if error
+ */
+FREENECTAPI int freenect_set_video_mode(freenect_device* dev, const freenect_frame_mode mode);
+
+/**
+ * Get the number of depth camera modes supported by the driver.  This includes both RGB and IR modes.
+ *
+ * @return Number of depth modes supported by the driver
+ */
+FREENECTAPI int freenect_get_depth_mode_count();
+
+/**
+ * Get the frame descriptor of the nth supported depth mode for the
+ * depth camera.
+ *
+ * @param n Which of the supported modes to return information about
+ *
+ * @return A freenect_frame_mode describing the nth depth mode
+ */
+FREENECTAPI const freenect_frame_mode freenect_get_depth_mode(int mode_num);
+
+/**
+ * Get the frame descriptor of the current depth mode for the specified
+ * freenect device.
+ *
+ * @param dev Which device to return the currently-set depth mode for
+ *
+ * @return A freenect_frame_mode describing the current depth mode of the specified device
+ */
+FREENECTAPI const freenect_frame_mode freenect_get_current_depth_mode(freenect_device *dev);
+
+/**
+ * Convenience function to return a mode descriptor matching the
+ * specified resolution and depth camera pixel format, if one exists.
+ *
+ * @param res Resolution desired
+ * @param fmt Pixel format desired
+ *
+ * @return A freenect_frame_mode that matches the arguments specified, if such a valid mode exists; otherwise, an invalid freenect_frame_mode.
+ */
+FREENECTAPI const freenect_frame_mode freenect_find_depth_mode(freenect_resolution res, freenect_depth_format fmt);
+
+/**
+ * Sets the current depth mode for the specified device.  The mode
+ * cannot be changed while streaming is active.
+ *
+ * @param dev Device for which to set the depth mode
+ * @param mode Frame mode to set
+ *
+ * @return 0 on success, < 0 if error
  */
-FREENECTAPI int freenect_set_video_resolution(freenect_device *dev, freenect_video_resolution res);
+FREENECTAPI int freenect_set_depth_mode(freenect_device* dev, const freenect_frame_mode mode);
 
 #ifdef __cplusplus
 }