| jpayne@68: | |
jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68:
jpayne@68: Function overloading (having a several variants of a function jpayne@68: with the same name and different arguments) is a language jpayne@68: feature available in many languages but not in C. jpayne@68:
jpayne@68:
jpayne@68: In general, language binding authors should use restraint in
jpayne@68: combining functions in the cairo API via function
jpayne@68: overloading. What may seem like an obvious overload now may
jpayne@68: turn out to be strange with future additions to cairo.
jpayne@68: It might seem logical to make
jpayne@68: cairo_set_source_rgb()
jpayne@68: an overload of cairo_set_source(), but future plans to add
jpayne@68: cairo_set_source_rgb_premultiplied(),
jpayne@68: which will also take three doubles make this a bad idea. For
jpayne@68: this reason, only the following pairs of functions should
jpayne@68: be combined via overloading
jpayne@68:
jpayne@68: void jpayne@68: cairo_set_source (cairo_t *cr, cairo_pattern_t *source); jpayne@68: jpayne@68: void jpayne@68: cairo_set_source_surface (cairo_t *cr, jpayne@68: cairo_surface_t *source, jpayne@68: double surface_x, jpayne@68: double surface_y); jpayne@68: jpayne@68: void jpayne@68: cairo_mask (cairo_t *cr, jpayne@68: cairo_pattern_t *pattern); jpayne@68: jpayne@68: void jpayne@68: cairo_mask_surface (cairo_t *cr, jpayne@68: cairo_surface_t *surface, jpayne@68: double surface_x, jpayne@68: double surface_y); jpayne@68: jpayne@68: cairo_surface_t * jpayne@68: cairo_image_surface_create (cairo_format_t format, jpayne@68: int width, jpayne@68: int height); jpayne@68: cairo_surface_t * jpayne@68: cairo_image_surface_create_for_data (unsigned char *data, jpayne@68: cairo_format_t format, jpayne@68: int width, jpayne@68: int height, jpayne@68: int stride); jpayne@68: jpayne@68: cairo_status_t jpayne@68: cairo_surface_write_to_png (cairo_surface_t *surface, jpayne@68: const char *filename); jpayne@68: jpayne@68: cairo_status_t jpayne@68: cairo_surface_write_to_png_stream (cairo_surface_t *surface, jpayne@68: cairo_write_func_t write_func, jpayne@68: void *closure); jpayne@68: jpayne@68: cairo_surface_t * jpayne@68: cairo_image_surface_create_from_png (const char *filename); jpayne@68: jpayne@68: cairo_surface_t * jpayne@68: cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func, jpayne@68: void *closure); jpayne@68:jpayne@68:
jpayne@68: Note that there are cases where all constructors for a type
jpayne@68: aren't overloaded together. For example
jpayne@68: cairo_image_surface_create_from_png()
jpayne@68: should not be overloaded together with
jpayne@68: cairo_image_surface_create().
jpayne@68: In such cases, the remaining constructors will typically need to
jpayne@68: be bound as static methods. In Java, for example, we might have:
jpayne@68:
jpayne@68: Surface surface1 = ImageSurface(Format.RGB24, 100, 100);
jpayne@68: Surface surface2 = ImageSurface.createFromPNG("camera.png");
jpayne@68: jpayne@68: Some other overloads that add combinations not found in C may be jpayne@68: convenient for users for language bindings that provide jpayne@68: cairo_point_t and cairo_rectangle_t jpayne@68: types, for example: jpayne@68:
jpayne@68:jpayne@68: void jpayne@68: cairo_move_to (cairo_t *cr, jpayne@68: cairo_point_t *point); jpayne@68: void jpayne@68: cairo_rectangle (cairo_t *cr, jpayne@68: cairo_rectangle_t *rectangle); jpayne@68:jpayne@68: