From: glima Date: Fri, 5 Aug 2011 20:16:19 +0000 (+0000) Subject: [ecore] Examples for the last batch of documentation X-Git-Tag: accepted/2.0/20130306.224007~156^2~170 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=9375fcf85f50d8f51fb45e4771426afe7a1bfe77;p=profile%2Fivi%2Fecore.git [ecore] Examples for the last batch of documentation bumps. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/ecore@62152 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- diff --git a/doc/examples.dox b/doc/examples.dox index 9f9a207..71253cb 100644 --- a/doc/examples.dox +++ b/doc/examples.dox @@ -17,7 +17,9 @@ * @li @ref ecore_evas_callbacks_example_c * @li @ref ecore_evas_object_example_c * @li @ref ecore_evas_basics_example_c - * + * @li Ecore_Evas_Window_Sizes_Example_c + * @li Ecore_Evas_Buffer_Example_01_c + * @li Ecore_Evas_Buffer_Example_02_c */ /** @@ -1378,4 +1380,89 @@ * Here you have the full-source of the code: * @include ecore_evas_basics_example.c * @example ecore_evas_basics_example.c - */ \ No newline at end of file + */ + +/** + * @page Ecore_Evas_Buffer_Example_01_c @c Ecore_Evas buffer example + * + * Between the Evas examples, there is one in which one creates a + * canvas bound to the Evas @b buffer engine and uses its pixel + * contents to create an PPM image on disk. There, one does that by + * creating the canvas "by hand", with @c evas_new(), @c + * evas_engine_info_set(), etc. + * + * On this example, we accomplish the very same task, but by using the + * @c Ecore_Evas helper wrapper functions on a buffer engine + * canvas. If you compare both codes, you'll see how much code one is + * saved from by using the @Ecore_Evas wrapper functions. + * + * The code is simple as it can be. After instantianting our canvas + * window, with ecore_evas_buffer_new(), we grab its canvas pointer + * and create the desired objects scene on it, which in this case is + * formed by 3 rectangles over the top left corner of a white + * background: + * @dontinclude ecore_evas_buffer_example_01.c + * @skip main(void) + * @until show(r3) + * + * Since it's a buffer canvas and we're using it to only save its + * contents on a file, we even needn't ecore_evas_show() it. We make + * it render itself, forcefully, without the aid of Ecore's mainloop, + * with ecore_evas_manual_render(): + * @dontinclude ecore_evas_buffer_example_01.c + * @skip manual_render + * @until manual_render + * + * And we're ready to save the window's shiny rendered contents as a + * simple PPM image. We do so by grabbing the pixels of the @c + * Ecore_Evas' internal canvas, with ecore_evas_buffer_pixels_get(): + * @dontinclude ecore_evas_buffer_example_01.c + * @skip _scene_save + * @until } + * @dontinclude ecore_evas_buffer_example_01.c + * @skip support function + * @until } + * @until } + * @until } + * + * Check that destination file for the result. The full example + * follows. + * + * @include ecore_evas_buffer_example_01.c + * @example ecore_evas_buffer_example_01.c + */ + +/** + * @page Ecore_Evas_Buffer_Example_02_c @c Ecore_Evas (image) buffer example + * + * In this example, we'll demonstrate the use of + * ecore_evas_object_image_new(). The idea is to have the same scene + * created for @ref Ecore_Evas_Buffer_Example_01_c as the contents of + * an image object. + * + * The canvas receiving this image object will have a white + * background, a red border image to delimit this image's boundaries + * and the image itself. After we create the special image, we set + * its "fill" property, place and resize it as we want. We have also + * to resize its underlying @c Ecore_Evas too, to the same dimensions: + * @dontinclude ecore_evas_buffer_example_02.c + * @skip object_image_new + * @until resize(sub_ee + * + * Now, we re-create the scene we cited, using the sub-canvas of our + * image to parent the objects in question. Because image objects are + * created with the alpha channel enabled, by default, we'll be seeing + * our white rectangle beneath the scene: + * @dontinclude ecore_evas_buffer_example_02.c + * @skip rectangle_add(sub_canvas + * @until loop_begin + * + * And that's all. The contents of our image could be updated as one + * wished, and they would always be mirrored in the image's area. + * + * Check that destination file for the result. The full example + * follows. + * + * @include ecore_evas_buffer_example_02.c + * @example ecore_evas_buffer_example_02.c + */ diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am index 58d2052..48eab32 100644 --- a/src/examples/Makefile.am +++ b/src/examples/Makefile.am @@ -2,12 +2,16 @@ MAINTAINERCLEANFILES = Makefile.in pkglibdir = $(datadir)/$(PACKAGE)/examples +filesdir = $(datadir)/$(PACKAGE)/examples +files_DATA = + AM_CPPFLAGS = \ -I. \ -I$(top_srcdir)/src/lib/ecore \ -I$(top_srcdir)/src/lib/ecore_evas \ -I$(top_srcdir)/src/lib/ecore_input \ -I$(top_srcdir)/src/lib/ecore_con \ +-DPACKAGE_EXAMPLES_DIR=\"$(datadir)/$(PACKAGE)/examples\" \ @GLIB_CFLAGS@ @EVIL_CFLAGS@ @EVAS_CFLAGS@ @EINA_CFLAGS@ @WIN32_CPPFLAGS@ @EFL_ECORE_BUILD@ ECOREBASELDADD = \ @@ -47,15 +51,18 @@ SRCS = \ ecore_evas_callbacks.c \ ecore_evas_window_sizes_example.c \ ecore_evas_object_example.c \ - ecore_evas_basics_example.c + ecore_evas_basics_example.c \ + ecore_evas_buffer_example_01.c \ + ecore_evas_buffer_example_02.c -EXTRA_DIST = $(SRCS) +EXTRA_DIST = $(SRCS) \ + $(srcdir)/red.png pkglib_PROGRAMS = if EFL_INSTALL_EXAMPLES -filesdir = $(datadir)/$(PACKAGE)/examples -files_DATA = $(SRCS) +files_DATA += $(SRCS) \ + $(srcdir)/red.png endif if EFL_BUILD_EXAMPLES @@ -80,7 +87,9 @@ pkglib_PROGRAMS += \ ecore_evas_callbacks \ ecore_evas_window_sizes_example \ ecore_evas_object_example \ - ecore_evas_basics_example + ecore_evas_basics_example \ + ecore_evas_buffer_example_01 \ + ecore_evas_buffer_example_02 ecore_con_lookup_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la ecore_con_url_headers_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la @@ -90,6 +99,7 @@ ecore_con_server_simple_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/li ecore_con_server_http_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la ecore_con_client_simple_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la ecore_evas_window_sizes_example_LDADD = $(ECOREBASELDADD) @EVAS_LIBS@ $(top_builddir)/src/lib/ecore_evas/libecore_evas.la +ecore_evas_buffer_example_01_LDADD = $(ECOREBASELDADD) @EVAS_LIBS@ $(top_builddir)/src/lib/ecore_evas/libecore_evas.la +ecore_evas_buffer_example_02_LDADD = $(ECOREBASELDADD) @EVAS_LIBS@ $(top_builddir)/src/lib/ecore_evas/libecore_evas.la endif - diff --git a/src/examples/ecore_evas_buffer_example_01.c b/src/examples/ecore_evas_buffer_example_01.c new file mode 100644 index 0000000..af05530 --- /dev/null +++ b/src/examples/ecore_evas_buffer_example_01.c @@ -0,0 +1,121 @@ +/** + * Simple Ecore_Evas example on the Evas buffer engine wrapper + * functions. + * + * You must have Evas compiled with the buffer engine. + * + * Compile with: + * + * @verbatim + * gcc -o evas-buffer-simple evas-buffer-simple.c `pkg-config --libs --cflags evas evas-software-buffer` + * @endverbatim + * + */ + +#ifdef HAVE_CONFIG_H + +#include "config.h" +#else +#define __UNUSED__ +#endif + +#include +#include + +#define WIDTH (320) +#define HEIGHT (240) + +static Ecore_Evas *ee; + +/* support function to save scene as PPM image */ +static void +_scene_save(Evas *canvas, + const char *dest) +{ + const unsigned int *pixels, *pixels_end; + int width, height; + FILE *f; + + evas_output_size_get(canvas, &width, &height); + + f = fopen(dest, "wb+"); + if (!f) + { + fprintf(stderr, "ERROR: could not open for writing '%s': %s\n", + dest, strerror(errno)); + return; + } + + pixels = ecore_evas_buffer_pixels_get(ee); + pixels_end = pixels + (width * height); + + /* PPM P6 format is dead simple to write: */ + fprintf(f, "P6\n%d %d\n255\n", width, height); + for (; pixels < pixels_end; pixels++) + { + int r, g, b; + + r = ((*pixels) & 0xff0000) >> 16; + g = ((*pixels) & 0x00ff00) >> 8; + b = (*pixels) & 0x0000ff; + + fprintf(f, "%c%c%c", r, g, b); + } + + fclose(f); + printf("Saved scene as '%s'\n", dest); +} + +int +main(void) +{ + Evas *canvas; + Evas_Object *bg, *r1, *r2, *r3; + + ecore_evas_init(); + + ee = ecore_evas_buffer_new(WIDTH, HEIGHT); + if (!ee) goto error; + + canvas = ecore_evas_get(ee); + + bg = evas_object_rectangle_add(canvas); + evas_object_color_set(bg, 255, 255, 255, 255); /* white bg */ + evas_object_move(bg, 0, 0); /* at origin */ + evas_object_resize(bg, WIDTH, HEIGHT); /* covers full canvas */ + evas_object_show(bg); + + r1 = evas_object_rectangle_add(canvas); + evas_object_color_set(r1, 255, 0, 0, 255); /* 100% opaque red */ + evas_object_move(r1, 10, 10); + evas_object_resize(r1, 100, 100); + evas_object_show(r1); + + r2 = evas_object_rectangle_add(canvas); + evas_object_color_set(r2, 0, 128, 0, 128); /* 50% opaque green */ + evas_object_move(r2, 10, 10); + evas_object_resize(r2, 50, 50); + evas_object_show(r2); + + r3 = evas_object_rectangle_add(canvas); + evas_object_color_set(r3, 0, 128, 0, 255); /* 100% opaque dark green */ + evas_object_move(r3, 60, 60); + evas_object_resize(r3, 50, 50); + evas_object_show(r3); + + ecore_evas_manual_render(ee); + _scene_save(canvas, "/tmp/evas-buffer-simple-render.ppm"); + + ecore_evas_free(ee); + ecore_evas_shutdown(); + + return 0; + +error: + fprintf(stderr, "You got to have at least one Evas engine built" + " and linked up to ecore-evas for this example to run" + " properly.\n"); + ecore_evas_shutdown(); + return -1; +} + diff --git a/src/examples/ecore_evas_buffer_example_02.c b/src/examples/ecore_evas_buffer_example_02.c new file mode 100644 index 0000000..29b7b3d --- /dev/null +++ b/src/examples/ecore_evas_buffer_example_02.c @@ -0,0 +1,126 @@ +/** + * Simple Ecore_Evas example on the Evas buffer engine wrapper + * functions. + * + * You must have Evas compiled with the buffer engine. + * + * Compile with: + * + * @verbatim + * gcc -o evas-buffer-simple evas-buffer-simple.c `pkg-config --libs --cflags evas evas-software-buffer` + * @endverbatim + * + */ + +#ifdef HAVE_CONFIG_H + +#include "config.h" +#else +#define __UNUSED__ +#define PACKAGE_EXAMPLES_DIR "." +#endif + +#include +#include +#include + +#define WIDTH (320) +#define HEIGHT (240) + +static Ecore_Evas *ee; +static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png"; + +static void +_on_destroy(Ecore_Evas *ee __UNUSED__) +{ + ecore_main_loop_quit(); +} + +int +main(void) +{ + Evas *canvas, *sub_canvas; + Evas_Object *bg, *r1, *r2, *r3; /* "sub" canvas objects */ + Evas_Object *border, *img; /* canvas objects */ + Ecore_Evas *sub_ee; + + ecore_evas_init(); + + /* this will give you a window with an Evas canvas under the first + * engine available */ + ee = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL); + if (!ee) goto error; + + ecore_evas_size_min_set(ee, WIDTH, HEIGHT); + ecore_evas_size_max_set(ee, WIDTH, HEIGHT); + + ecore_evas_callback_delete_request_set(ee, _on_destroy); + ecore_evas_title_set(ee, "Ecore_Evas buffer (image) example"); + ecore_evas_show(ee); + + canvas = ecore_evas_get(ee); + + bg = evas_object_rectangle_add(canvas); + evas_object_color_set(bg, 255, 255, 255, 255); /* white bg */ + evas_object_move(bg, 0, 0); /* at origin */ + evas_object_resize(bg, WIDTH, HEIGHT); /* covers full canvas */ + evas_object_show(bg); + + /* this is a border around the image containing a scene of another + * canvas */ + border = evas_object_image_filled_add(canvas); + evas_object_image_file_set(border, border_img_path, NULL); + evas_object_image_border_set(border, 3, 3, 3, 3); + evas_object_image_border_center_fill_set(border, EVAS_BORDER_FILL_NONE); + + evas_object_move(border, WIDTH / 6, HEIGHT / 6); + evas_object_resize(border, (2 * WIDTH) / 3, (2 * HEIGHT) / 3); + evas_object_show(border); + + img = ecore_evas_object_image_new(ee); + evas_object_image_filled_set(img, EINA_TRUE); + evas_object_image_size_set( + img, ((2 * WIDTH) / 3) - 6, ((2 * HEIGHT) / 3) - 6); + sub_ee = ecore_evas_object_ecore_evas_get(img); + sub_canvas = ecore_evas_object_evas_get(img); + + evas_object_move(img, (WIDTH / 6) + 3, (HEIGHT / 6) + 3); + + /* apply the same size on both! */ + evas_object_resize(img, ((2 * WIDTH) / 3) - 6, ((2 * HEIGHT) / 3) - 6); + ecore_evas_resize(sub_ee, ((2 * WIDTH) / 3) - 6, ((2 * HEIGHT) / 3) - 6); + + r1 = evas_object_rectangle_add(sub_canvas); + evas_object_color_set(r1, 255, 0, 0, 255); /* 100% opaque red */ + evas_object_move(r1, 10, 10); + evas_object_resize(r1, 100, 100); + evas_object_show(r1); + + r2 = evas_object_rectangle_add(sub_canvas); + evas_object_color_set(r2, 0, 128, 0, 128); /* 50% opaque green */ + evas_object_move(r2, 10, 10); + evas_object_resize(r2, 50, 50); + evas_object_show(r2); + + r3 = evas_object_rectangle_add(sub_canvas); + evas_object_color_set(r3, 0, 128, 0, 255); /* 100% opaque dark green */ + evas_object_move(r3, 60, 60); + evas_object_resize(r3, 50, 50); + evas_object_show(r3); + + evas_object_show(img); + ecore_main_loop_begin(); + + ecore_evas_free(ee); + ecore_evas_shutdown(); + + return 0; + +error: + fprintf(stderr, "You got to have at least one Evas engine built" + " and linked up to ecore-evas for this example to run" + " properly.\n"); + ecore_evas_shutdown(); + return -1; +} + diff --git a/src/examples/red.png b/src/examples/red.png new file mode 100644 index 0000000..dd03528 Binary files /dev/null and b/src/examples/red.png differ diff --git a/src/lib/ecore_evas/Ecore_Evas.h b/src/lib/ecore_evas/Ecore_Evas.h index da75f2a..6a6da20 100644 --- a/src/lib/ecore_evas/Ecore_Evas.h +++ b/src/lib/ecore_evas/Ecore_Evas.h @@ -62,6 +62,8 @@ extern "C" { * * This is a list of examples of these functions: * - @ref Ecore_Evas_Window_Sizes_Example_c + * - @ref Ecore_Evas_Buffer_Example_01_c + * - @ref Ecore_Evas_Buffer_Example_02_c * @{ */ @@ -750,16 +752,20 @@ EAPI const void *ecore_evas_buffer_pixels_get(Ecore_Evas *ee); * the canvas of @p ee, though, being exactly the image data of the * object returned by this function. * - * This is a helper function for the scenario of one willing to grab a + * This is a helper function for the scenario of one wanting to grab a * buffer canvas' contents (with ecore_evas_buffer_pixels_get()) to be * used on another canvas, for whichever reason. The most common goal * of this setup is to @b save an image file with a whole canvas as * contents, which could not be achieved by using an image file within * the target canvas. * - * @warning Always resize the returned image and its underlying @c - * Ecore_Evas handle accordingly and successively. They must be kept - * with same sizes for things to work as expected. + * @warning Always resize the returned image and its underlying + * @c Ecore_Evas handle accordingly. They must be kept with same sizes + * for things to work as expected. Also, you @b must issue + * @c evas_object_image_size_set() on the image with that same size. If + * the image is to be shown in a canvas bound to an engine different + * than the buffer one, then you must also set this image's @b fill + * properties accordingly. * * @note The image returned will always be bound to the * @c EVAS_COLORSPACE_ARGB8888 colorspace, always.